Open-source Revit MCP server: let Claude and other AI assistants read and edit BIM models, with human approval on every change.
Python aecai-agentsautodeskautomationbimclaudeifcmcpmcp-servermodel-context-protocolnavisworksrevitrevit-addinrevit-apirhino
feat: Enhance README with detailed installation, features, architecture, security, and usage examples.
A. Sam Mohammad1ea3ba0d4d2c
diff --git a/README.md b/README.mdindex 5d64f98..6733dfb 100644--- a/README.md+++ b/README.md@@ -1,175 +1,333 @@<div align="center">-# ποΈ Revit MCP Bridge--**Control Autodesk Revit from AI agents, Python scripts, or any MCP client**--<br/>--<p align="center">- <img src="https://raw.githubusercontent.com/modelcontextprotocol/docs/main/logo/light.svg" alt="MCP" height="60"/>- - <span style="font-size: 2em;">+</span>- - <img src="https://iconlogovector.com/logo/revit" alt="Revit" height="60"/>- - <span style="font-size: 2em;">=</span>- - <img src="https://www.vectorlogo.zone/logos/python/python-icon.svg" alt="Python" height="60"/>- - <span style="font-size: 2em;">+</span>- - <img src="https://cdn.worldvectorlogo.com/logos/c--4.svg" alt="C#" height="60"/>-</p>--<br/>--[](https://github.com/Sam-AEC/mcp/actions)-[](LICENSE)-[](https://autodesk.com/revit)-[](https://python.org)-[](https://dotnet.microsoft.com)+<img src="https://raw.githubusercontent.com/modelcontextprotocol/docs/main/logo/light.svg" alt="MCP Logo" width="120"/>++# Revit MCP Server++**Model Context Protocol server for Autodesk Revit automation**++Control Revit from AI agents, Python scripts, or any MCP-compatible client through a standardized interface.++[](LICENSE)+[](https://www.python.org/downloads/)+[](https://dotnet.microsoft.com/)+[](https://www.autodesk.com/products/revit)++[Installation](#installation) β’ [Features](#features) β’ [Architecture](#architecture) β’ [Documentation](#documentation)</div>----## What It Does+## Overview++This project provides a bridge between the Model Context Protocol (MCP) and Autodesk Revit, enabling programmatic control of Revit through a standardized API. It exposes 25 Revit operations for quality assurance, data extraction, and automation workflows.++**Key Components:**++- **MCP Server** (Python): Protocol handler with request validation, workspace sandboxing, and audit logging+- **Bridge Add-in** (C# .NET): Native Revit add-in that executes API calls via ExternalEvent+- **Mock Mode**: Standalone testing mode with deterministic responses (no Revit required)-Exposes **25 Revit operations** through the Model Context Protocol. Use it with:-- π€ AI agents (Claude, ChatGPT, custom tools)-- π Python/TypeScript automation-- π CI/CD pipelines-- βοΈ Cloud workflows+**Use Cases:**-**Components:**-- **MCP Server** (Python) β Validates requests, enforces sandboxing, logs everything-- **Bridge Add-in** (C# .NET) β Runs inside Revit, executes API calls via ExternalEvent-- **Mock Mode** β Test without Revit (perfect for CI)+- Automated quality assurance in CI/CD pipelines+- AI-powered model analysis and reporting+- Batch data extraction and exports+- Integration with custom tooling and workflows----## Quick Start+## Installation-### Mock Mode (No Revit Required)+### Prerequisites++**For Mock Mode (Testing/Development):**+- Python 3.11 or higher+- Git++**For Bridge Mode (Production with Revit):**+- Windows 10/11+- Autodesk Revit 2020-2024+- .NET Framework 4.8+- Visual Studio Build Tools or MSBuild++### Quick Start++#### 1. Clone and Install```bash-git clone https://github.com/Sam-AEC/mcp.git && cd mcp-python -m venv venv && source venv/bin/activate+git clone https://github.com/Sam-AEC/mcp.git+cd mcp+python -m venv venv+```++**Windows:**+```powershell+.\venv\Scripts\activate+```++**macOS/Linux:**+```bash+source venv/bin/activate+```++Install the MCP server:+```bashpip install -e packages/mcp-server-revit[dev]+```-export MCP_REVIT_MODE=mock WORKSPACE_DIR="$(pwd)/workspace"-mkdir -p workspace && pytest packages/mcp-server-revit/tests -v+#### 2. Run in Mock Mode++```bash+# Set environment variables+export MCP_REVIT_MODE=mock+export WORKSPACE_DIR="$(pwd)/workspace"+mkdir -p workspace-python -m revit_mcp_server # Terminal 1-python packages/client-demo/demo.py # Terminal 2+# Run tests+pytest packages/mcp-server-revit/tests -v++# Start server (terminal 1)+python -m revit_mcp_server++# Run demo client (terminal 2)+python packages/client-demo/demo.py```-### Bridge Mode (Windows + Revit)+#### 3. Run in Bridge Mode (Windows + Revit)```powershell-# After mock setup above...+# Build and install add-in$env:REVIT_SDK = "C:\Program Files\Autodesk\Revit 2024\SDK".\scripts\build-addin.ps1.\scripts\install-addin.ps1 -RevitYear 2024-# Start Revit, then:+# Start Revit, then configure and run server$env:MCP_REVIT_MODE = "bridge"+$env:WORKSPACE_DIR = "C:\revit-workspace"python -m revit_mcp_server```+For detailed installation instructions, see [docs/install.md](docs/install.md).+----## Tools (25)+## Features-| Category | Tools |-|----------|-------|-| **Health** | `revit.health` |-| **Documents** | `open_document`, `list_views` |-| **QA Audits** | `model_health_summary`, `warning_triage`, `naming_standards`, `parameter_compliance`, `shared_params`, `view_templates`, `tag_coverage`, `room_completeness`, `link_monitor`, `coordinate_check` |-| **Exports** | `schedules`, `quantities`, `pdf`, `dwg`, `ifc` |-| **Sheets** | `batch_create`, `place_views`, `titleblock_fill` |-| **Baseline** | `export`, `diff` |+### Available Tools (25)-[Full docs β](docs/tools.md)+| Category | Tools | Description |+|----------|-------|-------------|+| **Health Check** | `revit.health` | Server status and connectivity |+| **Document Management** | `open_document`, `list_views` | File operations and view enumeration |+| **Quality Assurance** | `model_health_summary`, `warning_triage`, `naming_standards`, `parameter_compliance`, `shared_params`, `view_templates`, `tag_coverage`, `room_completeness`, `link_monitor`, `coordinate_check` | Automated model validation and auditing |+| **Data Export** | `export_schedules`, `export_quantities`, `export_pdf`, `export_dwg`, `export_ifc` | Multi-format data extraction |+| **Sheet Management** | `batch_create_sheets`, `place_views_on_sheets`, `fill_titleblocks` | Sheet creation and configuration |+| **Baseline Tracking** | `export_baseline`, `diff_baseline` | Model comparison and change detection |----+Full tool documentation: [docs/tools.md](docs/tools.md)-## Example: AI QA Agent+### Security Features-```python-# Agent checks Revit model for issues-response = client.call_tool("revit.open_document", {- "file_path": "/workspace/hospital.rvt"-})+- **Workspace Sandboxing**: All file operations restricted to allowed directories+- **Schema Validation**: Pydantic-based request/response validation+- **Audit Logging**: JSONL logs with timestamps for all operations+- **Local-Only**: Bridge runs on localhost (no external network exposure)+- **Mock Mode**: Complete testing without Revit installation-warnings = client.call_tool("revit.warning_triage_report", {})-# β {"issues_found": 42, "severity": "warning"}+Security model: [docs/security.md](docs/security.md)-naming = client.call_tool("revit.naming_standards_audit", {})-# β Agent generates report with fixes+---++## Architecture++```+βββββββββββββββββββββββ+β AI Agent/Client β+β (Claude, ChatGPT) β+ββββββββββββ¬βββββββββββ+ β MCP Protocol (stdio/SSE)+ βΌ+βββββββββββββββββββββββ+β Python MCP Server β+β - Validation β+β - Sandboxing β+β - Logging β+ββββββββββββ¬βββββββββββ+ β HTTP (localhost:3000)+ βΌ+βββββββββββββββββββββββ+β C# Bridge Add-in β+β - ExternalEvent β+β - API Execution β+ββββββββββββ¬βββββββββββ+ β Revit API+ βΌ+βββββββββββββββββββββββ+β Autodesk Revit β+βββββββββββββββββββββββ```+**Why this architecture?**++The Revit API requires:+- .NET Framework (C# code)+- Windows operating system+- UI thread execution via ExternalEvent++This bridge architecture handles the complexity while exposing a simple, cross-platform JSON interface via MCP.++Detailed architecture: [docs/architecture.md](docs/architecture.md)+----## Architecture+## Usage Example++### Python Client+```python+from mcp import ClientSession, StdioServerParameters+from mcp.client.stdio import stdio_client++# Connect to MCP server+server_params = StdioServerParameters(+ command="python",+ args=["-m", "revit_mcp_server"],+ env={"MCP_REVIT_MODE": "bridge"}+)++async with stdio_client(server_params) as (read, write):+ async with ClientSession(read, write) as session:+ # Initialize+ await session.initialize()++ # Open document+ result = await session.call_tool(+ "revit.open_document",+ arguments={"file_path": "/workspace/project.rvt"}+ )++ # Run QA audit+ warnings = await session.call_tool(+ "revit.warning_triage_report",+ arguments={}+ )++ # Export data+ schedules = await session.call_tool(+ "revit.export_schedules",+ arguments={"output_dir": "/workspace/exports"}+ )```-AI Agent/Script- β (MCP stdio)-Python Server (validation, sandboxing, logging)- β (HTTP localhost:3000)-C# Bridge Add-in (ExternalEvent queue)- β (Revit API)-Autodesk Revit++### AI Agent Integration++Configure in your MCP client (Claude Desktop, Continue, etc.):++```json+{+ "mcpServers": {+ "revit": {+ "command": "python",+ "args": ["-m", "revit_mcp_server"],+ "env": {+ "MCP_REVIT_MODE": "bridge",+ "WORKSPACE_DIR": "C:\\revit-workspace"+ }+ }+ }+}```-**Why?** Revit API needs .NET + Windows + UI thread. This bridge handles complexity while exposing simple JSON tools.+The agent can then use natural language to control Revit:-[Architecture docs β](docs/architecture.md)+```+User: "Check the hospital.rvt model for warnings and naming violations"++Agent: [calls revit.open_document with hospital.rvt]+ [calls revit.warning_triage_report]+ [calls revit.naming_standards_audit]+ [generates report with findings and recommendations]+```----## Security+## Development-β Workspace sandboxing (paths validated)-β Schema validation (Pydantic)-β Audit logs (JSONL with timestamps)-β Mock mode (CI without Revit)-β localhost-only (no external exposure)+### Project Structure-[Security docs β](docs/security.md)+```+mcp/+βββ packages/+β βββ mcp-server-revit/ # Python MCP server+β βββ revit-bridge-addin/ # C# Revit add-in+β βββ client-demo/ # Example client+βββ scripts/ # Build and deployment scripts+βββ docs/ # Documentation+βββ examples/ # Configuration examples+```++### Running Tests++```bash+# Python tests+pytest packages/mcp-server-revit/tests -v++# C# tests (requires Visual Studio)+dotnet test packages/revit-bridge-addin/RevitBridge.Tests+```++### Contributing++See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.----## Use Cases+## Documentation-**Automated QA** β Run naming/parameter checks on every commit-**Scheduled Exports** β Nightly schedule/quantity exports to shared drives-**AI Workflows** β Let agents analyze models and suggest fixes-**Baseline Tracking** β Compare model snapshots over time+- **[Installation Guide](docs/install.md)**: Detailed setup for mock and bridge modes+- **[Tool Reference](docs/tools.md)**: Complete API documentation for all 25 tools+- **[Architecture](docs/architecture.md)**: System design and component interaction+- **[Security Model](docs/security.md)**: Trust boundaries and threat mitigation---## Roadmap-**Next (v0.2):** Real Revit API calls (currently stubs), async HTTP, error handling-**Later:** More QA tools, Dynamo integration, Navisworks export, BIM 360 support+**Version 0.2**+- Complete Revit API implementation (replace stubs)+- Async HTTP client with connection pooling+- Enhanced error handling and recovery+- Performance benchmarks++**Future**+- Additional QA tools (clash detection, BIM validation)+- Dynamo script integration+- Navisworks export support+- BIM 360/ACC integration+- Multi-document operations----## Docs+## License-[Install](docs/install.md) β’ [Tools](docs/tools.md) β’ [Architecture](docs/architecture.md) β’ [Security](docs/security.md) β’ [Contributing](CONTRIBUTING.md)+This project is licensed under the MIT License - see [LICENSE](LICENSE) for details.----## License+## Support-MIT β’ Built with [mcp-use](https://github.com/mcp-use/mcp-use) framework+- **Issues**: [GitHub Issues](https://github.com/Sam-AEC/mcp/issues)+- **Discussions**: [GitHub Discussions](https://github.com/Sam-AEC/mcp/discussions)+- **Documentation**: [docs/](docs/)++---<div align="center">-β **Star if useful** β’ [Report Bug](https://github.com/Sam-AEC/mcp/issues) β’ [Request Feature](https://github.com/Sam-AEC/mcp/issues)+Built with the [Model Context Protocol](https://modelcontextprotocol.io)++**[β Star this repo](https://github.com/Sam-AEC/mcp)** if you find it useful</div>