Speckle MCP Server

by bimgeek
Verified

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Integrations

  • Provides a bridge to Speckle's AEC (Architecture, Engineering, Construction) tools, allowing users to list, search, and retrieve projects, access model versions, and query object properties from BIM data.

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:

{ "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

License

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

-
security - not tested
F
license - not found
-
quality - not tested

A bridge between Speckle's API and client applications that enables users to list/search projects, access model versions, and retrieve/query objects and their properties from the Speckle collaborative data hub for AEC tools.

  1. Overview
    1. Installation
      1. Prerequisites
      2. Setup
    2. Configuration
      1. Environment Variables
      2. MCP Configuration
    3. Available Tools
      1. Projects
      2. Models
      3. Objects
    4. Troubleshooting
      1. License