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

Clone the repository
git clone <repository-url> cd thingiverse-mcp
Install dependencies
npm install
Set up environment variables
# Create development environment file cp .env.example .env.development # Create production environment file cp .env.example .env.production
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:

Start the MCP server Make sure your server is running locally or on a remote host that Claude Desktop can access.
Open Claude Desktop settings
- Launch Claude Desktop
- Click on your profile picture or icon in the top right
- Select "Settings" from the dropdown menu
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"
   ]
 }

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

Handles authentication via API tokens
Makes requests to various Thingiverse endpoints
Parses and returns the data in a structured format
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:

Ensure your .env.production file contains a valid Thingiverse API token
The build process will embed this token in the compiled code
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.

Integrations