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

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

Production Mode

Or use the shorthand:

🔗 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

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

⚙️ 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:

Linting and Formatting

📝 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.