Speckle MCP 服务器

与 Speckle 协作数据枢纽交互的 Model Context Protocol (MCP) 服务器，Speckle 连接您的 AEC 工具。

概述

此 MCP 服务器作为 Speckle API 和客户端应用程序之间的桥梁，并提供一组工具，允许用户：

• 列出和搜索 Speckle 项目
• 获取详细的项目信息
• 访问项目中的模型版本
• 获取并查询特定版本的对象及其属性

安装

先决条件

• Python 3.13 或更高版本
• 带有个人访问令牌的 Speckle 账户
• 使用 uv 进行依赖管理和虚拟环境

设置

1. 克隆此仓库：

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

2. 确保已安装 Python 3.13：

   python --version  # 应显示 Python 3.13.x
   

3. 使用 uv 安装依赖项：

   uv pip install -r requirements.txt
   

配置

环境变量

服务器需要以下环境变量：

• SPECKLE_TOKEN: 您的 Speckle 个人访问令牌（必需）
• SPECKLE_SERVER: Speckle 服务器 URL（默认为 https://app.speckle.systems）

MCP 配置

要将此服务器与 Claude 结合使用，您需要更新您的 MCP 配置文件。配置文件通常位于：

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

在 mcpServers 部分添加或更新 "speckle" 条目：

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

将 /path/to/speckle-mcp 替换为实际包含 speckle_mcp 包的目录路径。

可用工具

项目

• list_projects: 列出所有可访问的 Speckle 项目

  • 参数：
    • limit (可选): 要检索的最大项目数（默认：20）

• get_project_details: 获取特定项目的详细信息

  • 参数：
    • project_id: 要检索的 Speckle 项目的 ID
    • limit (可选): 要检索的最大模型数（默认：20）

• search_projects: 根据名称或描述搜索项目

  • 参数：
    • query: 在项目名称和描述中查找的搜索词

模型

• get_model_versions: 列出特定模型的所有版本
  • 参数：
    • project_id: Speckle 项目的 ID
    • model_id: 要检索版本的模型的 ID
    • limit (可选): 要检索的最大版本数（默认：20）

对象

• get_version_objects: 从特定版本获取对象

  • 参数：
    • project_id: Speckle 项目的 ID
    • version_id: 要从中检索对象的版本的 ID
    • include_children (可选): 是否在响应中包括子对象（默认：false）

• query_object_properties: 查询版本中对象的特定属性

  • 参数：
    • project_id: Speckle 项目的 ID
    • version_id: 要从中检索对象的版本的 ID
    • property_path: 属性的点符号路径（例如："elements.0.name"）

故障排除

• 如果遇到身份验证问题，请确保您的 Speckle 令牌有效且具有必要的权限
• 查看服务器日志以获取详细的错误消息
• 确保 MCP 配置中的环境变量设置正确

许可证

本项目根据 MIT 许可证发布 - 详情见 LICENSE 文件。 </中文翻译>