Thingiverse MCP Server

# Thingiverse MCP Server A Model Context Protocol (MCP) server that provides tools for interacting with the Thingiverse API, allowing AI assistants to search for, explore, and retrieve 3D printable models. [](https://www.typescriptlang.org/) [](https://nodejs.org/) ## 🌟 Overview This MCP server wraps the Thingiverse API using Puppeteer to create a reliable interface that can be used by AI assistants. It provides tools to: - Search for 3D printable models - Get random 3D models - Browse categories - Get models from specific categories ## 🚀 Features - **🔍 Model Search**: Search Thingiverse's database of 3D printable models using keywords - **🗂️ Category Browsing**: Explore models by categories - **🎲 Random Models**: Discover random 3D models from Thingiverse - **🌐 Complete API Access**: Get detailed information about models, including descriptions, files, images, and more - **🤖 AI Assistant Integration**: Designed to work with AI assistants through the Model Context Protocol ## 📋 Prerequisites - Node.js (v14 or higher) - npm or yarn - Thingiverse API token ## 🔧 Installation 1. **Clone the repository** ```bash git clone <repository-url> cd thingiverse-mcp ``` 2. **Install dependencies** ```bash npm install ``` 3. **Set up environment variables** ```bash # Create development environment file cp .env.example .env.development # Create production environment file cp .env.example .env.production ``` 4. **Configure API token** - Get a Thingiverse App Token from the [Thingiverse Developer Portal](https://www.thingiverse.com/developers) - Add your token to both `.env.development` and `.env.production` files: ``` APP_TOKEN=your_api_token_here ``` ## 🎮 Usage ### Development Mode ```bash npm run dev ``` This starts the MCP server in development mode with hot reload. ### Production Mode ```bash npm run build npm start ``` Or use the shorthand: ```bash npm run prod ``` ## 🔗 Integrating with Claude Desktop To add this MCP server to Claude Desktop and enable Thingiverse browsing capabilities: 1. **Start the MCP server** Make sure your server is running locally or on a remote host that Claude Desktop can access. 2. **Open Claude Desktop settings** - Launch Claude Desktop - Click on your profile picture or icon in the top right - Select "Settings" from the dropdown menu 3. **Navigate to Extensions settings** - In the Settings sidebar, click on "Extensions" - Select "Add Custom MCP" 4.1 **Configure the MCP connection** - Name: `Thingiverse MCP` (or any name you prefer) - URL: Enter the URL where your MCP server is running (e.g., `http://localhost:3000` for local development) - Click "Add MCP" 4.2 **Alternative Configure the MCP connection** - You first need to build the project and provide your full path C:/.../Thingiverse/dist/index.js ```json "thingiverse": { "command": "node", "args": [ "YOUR_CUSTOM_PATH/Thingiverse/dist/index.js" ] } ``` 5. **Enable the MCP** - Toggle the switch next to your newly added Thingiverse MCP to enable it - Claude Desktop will attempt to connect to your MCP server 6. **Verify connection** - Start a new conversation with Claude - Type "Can you help me find some 3D models on Thingiverse?" - Claude should now be able to use the Thingiverse tools to search and browse models 7. **Troubleshooting** - If Claude cannot connect to your MCP server, check that: - The server is running and accessible from Claude Desktop - The correct URL is configured in Claude Desktop settings - Your API token is valid and properly configured in the server ### Usage Examples with Claude Once connected, you can ask Claude to: - "Find me some 3D printable smartphone stands on Thingiverse" - "Show me some popular 3D models in the gadgets category" - "Get me a random 3D model from Thingiverse" - "What categories of 3D models are available on Thingiverse?" ## 🧠 Available Tools The server exposes several tools that can be used by AI assistants: ### `get-things` Searches for 3D models based on a search term. **Parameters:** - `term`: Search term (required) - `categoryId`: Optional category ID to narrow down search ### `get-random-thing` Retrieves random 3D models from Thingiverse. ### `get-categories` Fetches all available categories from Thingiverse. ### `get-random-thing-from-category` Gets random 3D models from a specific category. **Parameters:** - `categorySlug`: Category slug (required) ## 🔍 How It Works The server uses Puppeteer with Stealth plugin to interact with the Thingiverse API. This approach: 1. Handles authentication via API tokens 2. Makes requests to various Thingiverse endpoints 3. Parses and returns the data in a structured format 4. Exposes endpoints as MCP tools that can be called by AI assistants ## 🛠️ Project Structure ``` 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 ``` ## ⚙️ Development ### Environment Configuration The server uses different environment files for development and production: - `.env.development` - Used when running in development mode - `.env.production` - Used when running in production mode ### Testing Run the test suite with: ```bash npm test ``` ### Linting and Formatting ```bash # Run ESLint npm run lint # Fix ESLint errors npm run lint:fix # Format code with Prettier npm run format ``` ## 📝 Notes for Deployment When deploying to production: 1. Ensure your `.env.production` file contains a valid Thingiverse API token 2. The build process will embed this token in the compiled code 3. Use `npm run prod` to build and start the production server ## 📄 License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.