Speckle MCP Server

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

1. Clone this repository:
   git clone https://github.com/bimgeek/speckle-mcp.git cd speckle-mcp
2. Ensure you have Python 3.13 installed:
   python --version # Should show Python 3.13.x
3. 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:

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

License

This project is licensed under the MIT License - see the LICENSE file for details.