内容
# sketchfab-mcp-server
[](https://nodejs.org)
[](https://www.typescriptlang.org)
[](https://modelcontextprotocol.io)
[](https://sketchfab.com)
适用于 [Sketchfab](https://sketchfab.com) 的[模型上下文协议](https://modelcontextprotocol.io)服务器。从 Cursor、Claude Desktop 和其他 MCP 客户端搜索、浏览、检查和下载 3D 模型。
> **API 密钥要求：** 所有工具都需要有效的 **Sketchfab API令牌**。在 [sketchfab.com/settings/password](https://sketchfab.com/settings/password)（API令牌部分）创建一个令牌。通过 `--api-key`、`SKETCHFAB_API_KEY` 环境变量或在 MCP 客户端配置中传递它。
## 快速开始
### 前提条件
- **Node.js 18+** — MCP 服务器的运行时
- **Yarn** — 包管理器（或等效地使用 `npm` / `pnpm`）
- **Sketchfab API令牌** — 搜索、模型详情、类别、许可证和下载所需
- **Git** — 用于克隆仓库
### 从源代码构建
**克隆仓库：**
```bash
git clone https://github.com/AliRezaBeigy/sketchfab-mcp-server.git
cd sketchfab-mcp-server
```
**安装依赖并构建：**
```bash
yarn install
yarn build
```
**本地运行（stdio 传输）：**
```bash
# 选项 A：环境变量
export SKETCHFAB_API_KEY="your-api-token-here"
yarn start
# 选项 B：CLI 标志
node build/index.js --api-key "your-api-token-here"
```
**开发（无构建步骤）：**
```bash
export SKETCHFAB_API_KEY="your-api-token-here"
yarn dev
```
### 配置 MCP 客户端
将服务器添加到您的 MCP 客户端设置中。使用您机器上的 `build/index.js` 的绝对路径。
**Cursor** — 编辑 `~/.cursor/mcp.json`（或项目级 `.cursor/mcp.json`）：
```json
{
"mcpServers": {
"sketchfab": {
"command": "node",
"args": [
"/absolute/path/to/sketchfab-mcp-server/build/index.js"
],
"env": {
"SKETCHFAB_API_KEY": "your-api-token-here"
}
}
}
}
```
**Claude Desktop** — 编辑 `claude_desktop_config.json`:
```json
{
"mcpServers": {
"sketchfab": {
"command": "node",
"args": [
"/absolute/path/to/sketchfab-mcp-server/build/index.js"
],
"env": {
"SKETCHFAB_API_KEY": "your-api-token-here"
}
}
}
}
```
或者，将 API 密钥作为 CLI 参数传递，而不是 `env`:
```json
"args": [
"/absolute/path/to/sketchfab-mcp-server/build/index.js",
"--api-key",
"your-api-token-here"
]
```
保存后重启 MCP 客户端。服务器通过 **stdio** 通信；诊断信息仅写入 stderr。
### Windows
在 Windows 上，在 `mcp.json` 中的路径中使用反斜杠或正斜杠。PowerShell 示例用于一次性运行：
```powershell
$env:SKETCHFAB_API_KEY = "your-api-token-here"
node build\index.js
```
## MCP 工具
| 工具 | 描述 |
|------|-------------|
| `sketchfab-search` | 按关键词、标签、类别、许可证、用户等搜索模型 |
| `sketchfab-model-details` | 模型的完整元数据（统计信息、许可证、标签、可下载性） |
| `sketchfab-download` | 以 glTF、GLB、USDZ 或源（ZIP 自动解压）下载模型 |
| `sketchfab-list-categories` | 列出用于搜索筛选的类别 slug |
| `sketchfab-list-licenses` | 列出用于搜索筛选的许可证 slug |
**搜索筛选** 包括仅可下载、动画、绑定、精选、排序、日期范围（1/7/31 天）和基于光标的分页（每页最多 24 个结果）。
**下载格式：** `gltf`（默认）、`glb`、`usdz`、`source`。如果请求的格式不可用，服务器会回退到第一个可用格式。ZIP 存档（常见的 glTF/源）会自动保存和解压。
## 功能
- **Sketchfab API v3** — 通过官方 REST API 搜索、浏览和下载
- **丰富搜索** — 标签、类别、许可证、排序、分页和创作者筛选
- **模型下载** — glTF/GLB/USDZ/源，自动解压 ZIP
- **MCP 原生** — 与 Cursor、Claude Desktop 和任何 stdio MCP 主机一起工作
- **TypeScript** — 带有 Zod 参数验证的键控工具
## 许可证
参见项目许可证文件。
## 致谢
- [Sketchfab](https://sketchfab.com) — 3D 模型平台和 API
- [模型上下文协议](https://modelcontextprotocol.io) — AI 工具集成的开放标准
- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) — 官方 TypeScript MCP SDK
---
**为 3D 创作者和 AI 辅助工作流而打造 ❤️**
