pySC – AI-Powered Chat Interface for Autodesk Revit

Author: Sanjay Chauhan | GitHub

Natural language control of Revit models through Claude AI and the Model Context Protocol (MCP)

---

Overview

A native Revit plugin that provides a chat interface for controlling your BIM model using natural language. Built on Anthropic's Model Context Protocol with full conversation context and session persistence.

Example interactions:

• "Duplicate Level 1 and place it on a new sheet"
• "Find all walls longer than 20 feet"
• "List all grids" → "Hide them" (remembers context)
• "Calculate total conduit length by size"

Demo

---

System Architecture

Three-layer architecture connecting Revit to Claude AI:

• Revit Plugin (C# .NET 4.8) – WPF chat panel, WebSocket client, tool execution, model indexing
• MCP Server (Node.js/TypeScript) – WebSocket orchestration, Claude API integration, conversation management
• Claude AI (Anthropic) – Natural language processing, tool selection, response generation

---

How It Works

Message Flow

1. User types command in Revit chat panel
2. Plugin sends WebSocket message with model context (views, levels, selection)
3. Server forwards to Claude with conversation history and available tools
4. Claude selects appropriate tools and returns execution plan
5. Server sends commands back to plugin
6. Plugin executes via ExternalEvent (thread-safe)
7. Results return to Claude for natural language response

Connection Management

• Persistent WebSocket during active use
• Auto-disconnect after 15 minutes idle (prevents rate limiting)
• Auto-reconnect on next message
• Real-time connection status indicator

---

Features

Query & Analysis Element queries with parameter filtering Quantity takeoffs Schedule data export Selection & Visibility Select by category, level, family, type Select similar elements Hide/unhide categories Isolate elements View & Sheet Management Duplicate views Create sheets Place views on sheets Multi-step compound operations

MEP & Electrical Panel schedules Conduit calculations Bend analysis QA workflows Grid & Level Tools Copy/paste visibility states Toggle grid heads Align across views Drafting Batch tagging Sequential renumbering Duplicate detection

Context Awareness

• Maintains last 20 messages
• Tracks session state (selection, cached queries)
• Includes model context (active view, level)
• Smart pronoun resolution ("hide them" after "list grids")

---

Technical Details

Architecture

• Thread-safe – ExternalEvent pattern for Revit API calls
• Atomic transactions – Multi-step operations succeed or fail as one unit
• Composable tools – Inheritance-based design for easy extension
• Session persistence – SQLite-backed conversation history
• Performance optimized – Prompt caching reduces tokens from ~5000 to ~200 per request

Production Quality

• Automatic resource cleanup (WebSocket, GDI handles, timers)
• Connection resilience with auto-reconnect
• Comprehensive error logging with timestamps
• Race condition prevention
• Memory-efficient design

---

Installation

Prerequisites

• Autodesk Revit 2024
• Node.js 18.0+
• Anthropic API key

Setup

1. Clone repository

git clone https://github.com/schauh11/revit-mcp-server.git
cd revit-mcp-server

2. Configure MCP server

cd mcp-server
npm install
cp .env.example .env
# Edit .env and add your CLAUDE_API_KEY

3. Build plugin

• Open RevitPlugin/RevitPlugin.csproj in Visual Studio
• Build in Release mode
• Copy RevitPlugin.dll and RevitMCP.addin to:

  C:\ProgramData\Autodesk\Revit\Addins\2024\

• Edit RevitMCP.addin with correct DLL path

4. Launch

• Open Revit
• Find "pySC Chat" in Add-Ins ribbon
• Click "Start Server"

---

Example Workflows

Simple Query

"List all the walls"
→ Returns walls grouped by type

Context-Aware

"List all grids"
→ Shows grids with IDs

"Hide them"
→ Hides grids (remembers context)

Parameter Search

"Find all walls longer than 20 feet"
→ Stores 35 walls in session

"Which is the longest?"
→ Returns 81.0 ft wall from cache

Multi-Step

"Duplicate Level 2 and place on sheet A221"
→ Executes: duplicate view + create sheet + place viewport
   (single atomic transaction)

---

Troubleshooting

"Timeout: No response after 90 seconds"

• Verify server is running (console: "Server listening on port 3000")
• Check CLAUDE_API_KEY in .env
• Review rate limits at console.anthropic.com

"Auto-disconnected due to inactivity"

• Normal after 15 minutes idle
• Send any message to reconnect

"Failed to connect to MCP server"

• Click "Start Server" in panel
• Check port 3000 availability
• Restart Revit if needed

Slow responses (>20s)

• First request includes model indexing
• Subsequent requests use cache
• Check internet connection

---

Project Structure

revit-mcp-server/
├── RevitPlugin/              # C# plugin
│   ├── Commands/             # App lifecycle
│   ├── UI/                   # WPF chat panel
│   ├── Services/             # WebSocket, tools, indexing
│   └── Helpers/              # Utilities
├── mcp-server/               # TypeScript server
│   ├── src/
│   │   ├── index.ts
│   │   ├── websocketHandler.ts
│   │   ├── claudeClient.ts
│   │   └── logger.ts
│   └── tools.json            # Tool definitions
└── docs/                     # Diagrams

---

Contributing

Contributions welcome. Open an issue before major changes.

License

MIT License – see LICENSE

Free to use, modify, and distribute.

---

Built With

• Anthropic Claude – Claude Haiku 4.5
• Revit API – BIM automation
• Model Context Protocol – Tool orchestration