Subgor8126/sketchfab-mcp-server

Sketchfab MCP Server

A Model Context Protocol (MCP) server for interacting with Sketchfab's 3D model platform. This MCP allows you to search, view details, and download 3D models from Sketchfab directly through Claude or Cursor.

Features

• Search for 3D Models: Find models on Sketchfab using keywords, tags, and categories
• View Model Details: Get comprehensive information about specific models
• Download Models: Download models in various formats (gltf, glb, usdz, source)

Prerequisites

• Node.js 18 or higher
• A Sketchfab API key (for authentication)

Installation

1. Clone this repository
2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Usage

Using with Docker MCP Gateway (Recommended)

This server is designed to work with Docker MCP Gateway for secure, enterprise-ready deployment:

1. Enable the server:

   docker mcp server enable your-dockerhub-username/sketchfab-mcp-server
   

2. Set your API key:

   docker mcp secret set 'sketchfab.api_key=YOUR_API_KEY'
   

3. Run the gateway:

   docker mcp gateway run
   

4. Connect your MCP client (like Claude Desktop or VS Code) to the gateway.

Running Locally for Development

npm start

To provide your Sketchfab API key, use the --api-key parameter:

node build/index.js --api-key YOUR_API_KEY

Alternatively, you can set the SKETCHFAB_API_KEY environment variable:

export SKETCHFAB_API_KEY=YOUR_API_KEY
npm start

Building Docker Image

docker build -t your-dockerhub-username/sketchfab-mcp-server .
docker push your-dockerhub-username/sketchfab-mcp-server

Available Tools

1. sketchfab-search

Search for 3D models on Sketchfab based on keywords and filters.

Parameters:

• query (optional): Text search query (e.g., "car", "house", "character")
• tags (optional): Filter by specific tags (e.g., ["animated", "rigged", "pbr"])
• categories (optional): Filter by categories (e.g., ["characters", "architecture", "vehicles"])
• downloadable (optional): Set to true to show only downloadable models
• limit (optional): Maximum number of results to return (1-24, default: 10)

2. sketchfab-model-details

Get detailed information about a specific Sketchfab model.

Parameters:

• modelId: The unique ID of the Sketchfab model

3. sketchfab-download

Download a 3D model from Sketchfab.

Parameters:

• modelId: The unique ID of the Sketchfab model to download
• format (optional): Preferred format to download the model in (gltf, glb, usdz, source)
• outputPath (optional): Local directory or file path to save the downloaded file

Using with MCP Clients

With Docker MCP Gateway (Recommended)

The server is designed to work with Docker MCP Gateway, which handles all the complexity:

# Enable the server
docker mcp server enable your-dockerhub-username/sketchfab-mcp-server

# Set API key
docker mcp secret set 'sketchfab.api_key=YOUR_API_KEY'

# Run gateway
docker mcp gateway run

Then configure your MCP client to connect to the gateway endpoint.

Direct Integration (Local Development)

For local development, you can connect MCP clients directly:

With Claude Desktop

{
  "mcpServers": {
    "sketchfab": {
      "command": "node",
      "args": ["/path/to/build/index.js", "--api-key", "YOUR_API_KEY"]
    }
  }
}

With Cursor

1. Go to Cursor Settings -> MCP -> Add new MCP server
2. Configure your MCP:
   • Name: Sketchfab MCP
   • Type: command
   • Command: node /path/to/build/index.js --api-key YOUR_API_KEY

Environment Variables

You can set the following environment variables:

• SKETCHFAB_API_KEY: Your Sketchfab API key (alternative to passing it with the --api-key parameter)

Docker Hub Deployment

To push to Docker Hub:

1. Build the image:

   docker build -t your-dockerhub-username/sketchfab-mcp-server .
   

2. Push to Docker Hub:

   docker push your-dockerhub-username/sketchfab-mcp-server
   

The GitHub Actions workflow will automatically build and push to Docker Hub when you push to the main branch or create a release tag.

Docker MCP Gateway Integration

This server is designed to work seamlessly with Docker MCP Gateway, which provides:

• Secure container isolation for MCP servers
• Centralized secret management for API keys
• Enterprise-grade monitoring and logging
• Unified endpoint for multiple MCP servers
• Automatic discovery from Docker Hub

Credits

This project is based on the Sketchfab MCP Server by Greg Kopyltsov.

Key modifications made:

• Converted from stdio-only to Docker MCP Gateway compatible
• Added Docker containerization and multi-stage builds
• Enhanced for enterprise deployment with Docker MCP Gateway
• Added comprehensive Docker Hub CI/CD pipeline
• Updated documentation for Docker MCP Gateway usage

License

ISC