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

[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-339933?style=for-the-badge&logo=nodedotjs&logoColor=white)](https://nodejs.org/)


## 🌟 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**
   ```bash
   git clone <repository-url>
   cd thingiverse-mcp
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Set up environment variables**
   ```bash
   # 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](https://www.thingiverse.com/developers)
   - Add your token to both `.env.development` and `.env.production` files:
     ```
     APP_TOKEN=your_api_token_here
     ```

## 🎮 Usage

### Development Mode

```bash
npm run dev
```

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

### Production Mode

```bash
npm run build
npm start
```

Or use the shorthand:

```bash
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

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

```bash
npm test
```

### Linting and Formatting

```bash
# 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](LICENSE) file for details.