Thingiverse MCP 服务器

一个模型上下文协议 (MCP) 服务器，提供与 Thingiverse API 交互的工具，使 AI 助手能够搜索、探索和检索 3D 打印模型。

🌟 概览

这个 MCP 服务器使用 Puppeteer 包装了 Thingiverse API，创建了一个可靠的接口，可以被 AI 助手使用。它提供了以下工具：

• 搜索 3D 打印模型
• 获取随机 3D 模型
• 浏览分类
• 从特定分类中获取模型

🚀 特性

• 🔍 模型搜索：使用关键词搜索 Thingiverse 的 3D 打印模型数据库
• 🗂️ 分类浏览：按分类浏览模型
• 🎲 随机模型：发现来自 Thingiverse 的随机 3D 模型
• 🌐 完整 API 访问：获取模型的详细信息，包括描述、文件、图片等
• 🤖 AI 助手集成：通过模型上下文协议设计为与 AI 助手配合工作

📋 前提条件

• Node.js (v14 或更高版本)
• npm 或 yarn
• Thingiverse API 令牌

🔧 安装

1. 克隆仓库

   git clone <repository-url>
   cd thingiverse-mcp
   

2. 安装依赖

   npm install
   

3. 设置环境变量

   # 创建开发环境文件
   cp .env.example .env.development
   # 创建生产环境文件
   cp .env.example .env.production
   

4. 配置 API 令牌

   • 从 Thingiverse 开发者门户 获取 Thingiverse 应用令牌
   • 将您的令牌添加到 .env.development 和 .env.production 文件中：

     APP_TOKEN=your_api_token_here
     

🎮 使用

开发模式

npm run dev

这将以热重载方式启动 MCP 服务器在开发模式下。

生产模式

npm run build
npm start

或者使用简写：

npm run prod

🔗 与 Claude Desktop 集成

要将此 MCP 服务器添加到 Claude Desktop 并启用 Thingiverse 浏览功能：

1. 启动 MCP 服务器
   确保您的服务器正在本地运行或在 Claude Desktop 可以访问的远程主机上运行。

2. 打开 Claude Desktop 设置

   • 启动 Claude Desktop
   • 单击右上角的个人头像或图标
   • 从下拉菜单中选择“设置”

3. 导航到扩展设置

   • 在设置侧边栏中，点击“扩展”
   • 选择“添加自定义 MCP”

4.1 配置 MCP 连接

• 名称：Thingiverse MCP（或您喜欢的任何名称）
• URL：输入您的 MCP 服务器运行的 URL（例如，对于本地开发为 http://localhost:3000）
• 点击“添加 MCP”

4.2 替代配置 MCP 连接

• 首先，你需要构建项目并提供完整的路径 C:/.../Thingiverse/dist/index.js

"thingiverse": {
   "command": "node",
   "args": [
     "YOUR_CUSTOM_PATH/Thingiverse/dist/index.js"
   ]
 }

1. 启用 MCP

   • 切换你新添加的 Thingiverse MCP 旁边的开关以启用它
   • Claude 桌面版将尝试连接到你的 MCP 服务器

2. 验证连接

   • 开始与 Claude 的新对话
   • 输入 "你能帮我找一些 Thingiverse 上的 3D 模型吗？"
   • Claude 现在应该能够使用 Thingiverse 工具来搜索和浏览模型

3. 故障排除

   • 如果 Claude 无法连接到你的 MCP 服务器，请检查：
     • 服务器正在运行并且可以从 Claude 桌面版访问
     • 在 Claude 桌面版设置中配置了正确的 URL
     • 你的 API 令牌有效且在服务器中正确配置

使用示例

一旦连接成功，你可以要求 Claude：

• "在 Thingiverse 上找一些 3D 打印手机支架给我"
• "向我展示小工具类别中的一些热门 3D 模型"
• "从 Thingiverse 上随机获取一个 3D 模型"
• "Thingiverse 上有哪些类别的 3D 模型可用？"

🧠 可用工具

服务器公开了几个 AI 助手可以使用的工具：

get-things

根据搜索词搜索 3D 模型。

参数：

• term: 搜索词（必填）
• categoryId: 可选类别 ID 以缩小搜索范围

get-random-thing

从 Thingiverse 获取随机 3D 模型。

get-categories

从 Thingiverse 获取所有可用类别。

get-random-thing-from-category

从特定类别中获取随机 3D 模型。

参数：

• categorySlug: 类别标识符（必填）

🔍 工作原理

服务器使用带有 Stealth 插件的 Puppeteer 与 Thingiverse API 进行交互。这种方法：

1. 通过 API 令牌处理身份验证
2. 向各种 Thingiverse 端点发出请求
3. 解析并将数据以结构化格式返回
4. 将端点作为 MCP 工具公开，这些工具可以由 AI 助手调用

🛠️ 项目结构

src/
  ├── class/
  │   └── thingiverser.class.ts    # Main Puppeteer client for Thingiverse API
  ├── endpoints/
  │   ├── getCategories.ts         # Get all categories
  │   ├── getRandomThing.ts        # Get random things
  │   ├── getThings.ts             # Search for things
  │   └── getThingsFromCategory.ts # Get things from a category
  ├── types/
  │   ├── category.d.ts            # Type definitions for categories
  │   ├── files.d.ts               # Type definitions for files
  │   └── things.d.ts              # Type definitions for things
  └── index.ts                     # Entry point and MCP server setup

⚙️ 开发

环境配置

服务器使用不同的环境文件进行开发和生产：

• .env.development - 在开发模式下运行时使用
• .env.production - 在生产模式下运行时使用

测试

运行测试套件：

npm test

代码检查和格式化

# Run ESLint
npm run lint

# Fix ESLint errors
npm run lint:fix

# Format code with Prettier
npm run format

📝 部署注意事项

当部署到生产环境时：

1. 确保你的 .env.production 文件包含有效的 Thingiverse API 令牌
2. 构建过程会将此令牌嵌入编译后的代码中
3. 使用 npm run prod 命令构建并启动生产服务器

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。