Speckle

🚀 Speckle MCP Server

A Model Context Protocol (MCP) server for interacting with Speckle, a collaborative data hub that connects your AEC tools.

🚀 Quick Start

This MCP server serves as a bridge between the Speckle API and client applications, offering a suite of tools that enable users to:

• List and search Speckle projects.
• Obtain detailed information about specific projects.
• Access model versions within projects.
• Retrieve and query objects and their attributes for specific versions.

📦 Installation

Prerequisites

• Python 3.13 or higher.
• A Speckle account and a personal access token.
• uv for dependency management and virtual environments.

Setup

1. Clone this repository:

git clone https://github.com/bimgeek/speckle-mcp.git
cd speckle-mcp

2. Ensure Python 3.13 is installed:

python --version  # Should display Python 3.13.x

3. Install dependencies using uv:

uv pip install -r requirements.txt

📚 Documentation

Environment Variables

The server requires the following environment variables:

• SPECKLE_TOKEN: Your Speckle personal access token (required).
• SPECKLE_SERVER: The Speckle server URL (default: https://app.speckle.systems).

MCP Configuration

To use this server with Claude, you need to update your MCP configuration file. The configuration file is typically located at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add or update the "speckle" entry in the mcpServers section:

{
  "mcpServers": {
    "speckle": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/speckle-mcp",
        "run",
        "speckle_server.py"
      ],
      "env": {
        "SPECKLE_TOKEN": "YOUR_SPECKLE_API_TOKEN_HERE",
        "SPECKLE_SERVER": "https://app.speckle.systems"
      }
    }
  }
}

Replace /path/to/speckle-mcp with the actual path to the directory containing the speckle_mcp package.

✨ Features

Projects

• list_projects: List all accessible Speckle projects.
  • Parameters:
    • limit (optional): The maximum number of projects to retrieve (default: 20).
• get_project_details: Get detailed information about a specific project.
  • Parameters:
    • project_id: The ID of the Speckle project to retrieve.
    • limit (optional): The maximum number of models to retrieve (default: 20).
• search_projects: Search for projects by name or description.
  • Parameters:
    • query: The search term to look for in project names and descriptions.

Models

• get_model_versions: List all versions of a specific model.
  • Parameters:
    • project_id: The ID of the Speckle project.
    • model_id: The ID of the model to retrieve versions for.
    • limit (optional): The maximum number of versions to retrieve (default: 20).

Objects

• get_objects: Filter objects by type or attributes.
  • Parameters:
    • type (optional): The type of objects to find.
    • properties (optional): A list of attributes to include.
    • limit (optional): The maximum number of objects to retrieve (default: 20).

💡 Usage Tip

• Check if the token is set correctly and ensure it has appropriate permissions.
• View the server logs for more information.

📄 License

This project is licensed under the MIT License.