# speckle-mcp

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)

> **Connect Revit, Rhino, AutoCAD and more to AI agents.**
> Manage projects, models and versions through natural language. Data flows through native Speckle connectors — this MCP provides instructions and metadata.

---

## For Architects & Engineers

### What does this do?

Instead of opening 4 different apps to check project status, ask Claude:

> "Show me the latest model version in the Hospital project"

Claude connects to Speckle and tells you who sent what, when, and which discipline.

### What can I ask?

| You ask... | It does... |
|-----------|------------|
| "List my Speckle projects" | Shows all your projects with IDs and dates |
| "What models are in project X?" | Lists architecture, structure, MEP models |
| "Show me the version history" | Who sent what, when, with commit messages |
| "Create a new project for the school" | Creates a project ready for your team |
| "How do I send my Revit model?" | Step-by-step for Revit, Rhino, AutoCAD, Blender |
| "How do I receive the latest model?" | Instructions for pulling data into your BIM tool |

### How to install

**Step 1:** Install **uv**:
```
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"   # Windows
curl -LsSf https://astral.sh/uv/install.sh | sh               # Mac
```

**Step 2:** Get a free Speckle token at https://app.speckle.systems/profile

**Step 3:** Download and configure:
```
git clone https://github.com/Daviidro/speckle-mcp.git
cd speckle-mcp
uv sync
```

Add to Claude Desktop config:
```json
{
  "mcpServers": {
    "speckle": {
      "command": "uv",
      "args": ["run", "speckle-mcp"],
      "env": { "SPECKLE_TOKEN": "your-token-here" }
    }
  }
}
```

### Is this safe?

**Yes. Your Speckle data is protected by your personal access token.**

- You control which projects the token can access
- Revoke the token anytime from your Speckle profile
- The token stays on your computer — never sent anywhere except Speckle servers
- Open source (MIT) — inspect every line

---

## For Developers

### Tools

| Tool | Description |
|------|-------------|
| `speckle_projects_list` | List all accessible Speckle projects |
| `speckle_project_details` | Get project details, models, and team |
| `speckle_project_create` | Create a new Speckle project |
| `speckle_models_list` | List models in a project |
| `speckle_model_details` | Get model details with version history |
| `speckle_model_create` | Create a new model with discipline |
| `speckle_send_instructions` | Guidance for sending from Revit/Rhino/etc. |
| `speckle_receive_instructions` | Version info + guidance for receiving |

### Supported platforms
- Speckle Server: app.speckle.systems or self-hosted
- Connectors: Revit, Rhino, Grasshopper, AutoCAD, Archicad, Blender, SketchUp, Unity, Unreal, Power BI, QGIS, Excel

### Ecosystem
- [ifcopenshell-mcp](https://github.com/Daviidro/ifcopenshell-mcp) — Talk to IFC models
- [bim-agent](https://github.com/Daviidro/bim-agent) — Multi-MCP orchestrator
- [awesome-aec-mcp](https://github.com/Daviidro/awesome-aec-mcp) — Curated MCP list

## License

MIT — built on [Speckle](https://speckle.systems/) (Apache 2.0) and [MCP](https://modelcontextprotocol.io/).