Thingiverse

🚀 Thingiverse MCP Server

A Model Context Protocol (MCP) server that provides tools to interact with the Thingiverse API, allowing AI assistants to search, explore, and retrieve 3D printable models.

🚀 Quick Start

This server uses Puppeteer and the Stealth plugin to interact via the Thingiverse API, offering various tools for AI assistants to call. Here is the full documentation for the project.

✨ Features

• Search for models: Search for 3D models by keyword or category ID.
• Get a random model: Retrieve a random 3D model from Thingiverse.
• Get categories: Fetch all available 3D model categories.
• Get a random model from a category: Obtain a random 3D model from a specified category.

📦 Installation

Prerequisites

1. Install Node.js (version 14 or higher is recommended).
2. Install the npm package management tool.
3. Create and activate a virtual environment (optional but recommended).

Steps

1. Clone the project repository:

   git clone https://github.com/your-repository.git
   cd thingiverse-mcp-server
   

2. Install dependencies:

   npm install
   

3. Configure environment variables:
   • Create a .env.development file and add the Thingiverse API token.
   • Create a .env.production file and add the Thingiverse API token.
4. Run the development server:

   npm run dev
   

5. Build the production version:

   npm run build
   

6. Start the production server:

   npm start
   

💻 Usage Examples

get-things Tool

Search for 3D models by keyword or category ID. Parameters:

• term: Search keyword (required)
• categoryId: Optional category ID to narrow down the search

get-random-thing Tool

Retrieve a random 3D model from Thingiverse.

get-categories Tool

Fetch all available 3D model categories.

get-random-thing-from-category Tool

Obtain a random 3D model from a specified category. Parameters:

• categorySlug: Category identifier (required)

🔧 Technical Details

How it Works

The server uses Puppeteer and the Stealth plugin to interact via the Thingiverse API:

1. Handle authentication using the API token.
2. Call different endpoints of Thingiverse.
3. Parse and return structured data.
4. Expose MCP tools for AI assistants to call.

Project Structure

src/
├── class/
│   └── thingiverser.class.ts    # Main Puppeteer client
├── endpoints/
│   ├── getCategories.ts         # Get all categories
│   ├── getRandomThing.ts        # Get a random model
│   ├── getThings.ts             # Search for models
│   └── getThingsFromCategory.ts # Get models from a category
├── types/
│   ├── category.d.ts            # Category type definition
│   ├── files.d.ts               # File type definition
│   └── things.d.ts              # Model type definition
└── index.ts                     # Entry point and MCP server setup

Development Instructions

Environment Configuration

The project uses different environment files:

• .env.development: Used in development mode.
• .env.production: Used in production mode.

Testing

Run the test suite:

npm test

Formatting and Code Checking

# Run ESLint
npm run lint

# Fix ESLint errors
npm run lint:fix

# Format using Prettier
npm run format

Deployment Instructions

1. Ensure that the .env.production file contains a valid Thingiverse API token.
2. The build process will embed this token into 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.