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

Parameters:
- term: Search term (required)
- categoryId: Optional category ID to narrow down search

get-random-thing

get-categories

get-random-thing-from-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

```bash