Speckle Mcp

Speckle MCP Server

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

Overview

This MCP server acts as a bridge between Speckle’s API and client applications and exposes a set of tools that allow users to:

List and search Speckle projects
Retrieve detailed project information
Access model versions within projects
Retrieve and query objects and their properties from specific versions

Installation

Prerequisites

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

Setup

Clone this repository:

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

Ensure you have Python 3.13 installed:

python --version  # Should show Python 3.13.x

Install dependencies using uv:
```
uv pip install -r requirements.txt
```

Configuration

Environment Variables

The server requires the following environment variables:

SPECKLE_TOKEN: Your Speckle personal access token (required)
SPECKLE_SERVER: The Speckle server URL (defaults to 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.

Available Tools

Projects

list_projects: Lists all accessible Speckle projects
- Parameters:
  - limit (optional): Maximum number of projects to retrieve (default: 20)
get_project_details: Retrieves detailed information about a specific project
- Parameters:
  - project_id: The ID of the Speckle project to retrieve
  - limit (optional): Maximum number of models to retrieve (default: 20)
search_projects: Searches for projects by name or description
- Parameters:
  - query: The search term to look for in project names and descriptions

Models

get_model_versions: Lists all versions for 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): Maximum number of versions to retrieve (default: 20)

Objects

get_version_objects: Retrieves objects from a specific version
- Parameters:
  - project_id: The ID of the Speckle project
  - version_id: The ID of the version to retrieve objects from
  - include_children (optional): Whether to include children objects in the response (default: false)
query_object_properties: Queries specific properties from objects in a version
- Parameters:
  - project_id: The ID of the Speckle project
  - version_id: The ID of the version to retrieve objects from
  - property_path: The dot-notation path to the property (e.g., “elements.0.name”)

Troubleshooting

If you encounter authentication issues, make sure your Speckle token is valid and has the necessary permissions
Check the server logs for detailed error messages
Ensure the environment variables are correctly set in the MCP configuration