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.

🌟 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

   git clone <repository-url>
   cd thingiverse-mcp
   

2. Install dependencies

   npm install
   

3. Set up environment variables

   # 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
   • Add your token to both .env.development and .env.production files:

     APP_TOKEN=your_api_token_here
     

🎮 Usage

Development Mode

npm run dev

This starts the MCP server in development mode with hot reload.

Production Mode

npm run build
npm start

Or use the shorthand:

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

"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:

npm test

Linting and Formatting

# 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 file for details.