Skip to content
Back to search

mcp-server-for-revit-python

MCP server for Revit - Python

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mcp-servers-for-revit--mcp-server-for-revit-python/badge.svg)](/listings/mcp-servers-for-revit--mcp-server-for-revit-python)

HTML

<a href="/listings/mcp-servers-for-revit--mcp-server-for-revit-python"><img src="/api/listings/mcp-servers-for-revit--mcp-server-for-revit-python/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Installing uv:

> Refer to ./README_UV.md

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 464 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # MCP server for Revit - Python
  2. ## A pyRevit-oriented implementation of the Model Context Protocol (MCP) for Autodesk Revit
  3. ## Local pairing and Autodesk Marketplace publication
  4. This project is being prepared for Autodesk Marketplace review; it is not yet certified.
  5. The review candidate retains all 20 tools, including Python execution. See
  6. [publication requirements and outstanding gates](docs/autodesk-marketplace.md),
  7. [privacy information](PRIVACY.md), and [security boundaries](SECURITY.md).
  8. After installing the pyRevit extension, choose **MCP > Bridge > Connect** in Revit
  9. to consent and create an encrypted pairing secret for your Windows user. Choose
  10. **Disconnect** to revoke it. Requests that change models and Python execution show
  11. their payload for review in Revit before proceeding. Pairing also permits local
  12. Revit discovery and launch. Pairing is shared across Revit instances for the same
  13. Windows user; select the correct Routes port before connecting.
  14. The MCP-to-Revit bridge accepts only loopback hosts. Remote VM/LAN HTTP bridges are
  15. rejected. Optional HTTP MCP transports require a paired bearer header; `stdio` is
  16. the recommended publication transport and needs no token in client configuration.
  17. Do not expose either listener to a network, tunnel or the internet.
  18. ## **How?**
  19. - This minimal implementation leverages the Routes module inside pyRevit to create a bridge between Revit and Large Language Models (LLMs).
  20. - It provides a straightforward template to get started quickly, letting you prototype and iterate tools to give LLMs access to your Revit models.
  21. - These tools are designed to be expanded for your specific use cases. You're very welcome to fork the repo and make your own contributions.
  22. - **Note:** The pyRevit Routes API is currently in draft form and subject to change. This extension authenticates its own routes using Windows-user pairing. Other pyRevit routes/extensions remain outside this protection; review pyRevit server binding and the security document.
  23. ## **Batteries Included**
  24. This repo is aimed at:
  25. - Beginners to the Revit API
  26. - Python specialists who aren't versed in C#
  27. - Anyone wanting to prototype and iterate quickly with LLMs and Revit
  28. It contains:
  29. - A complete Routes implementation for pyRevit
  30. - A minimal MCP server script to connect to any MCP-compatible client
  31. - Several test commands to get you started right away
  32. ## Key Architecture Components
  33. The system runs as **two separate servers** working together in a chain:
  34. ```
  35. Claude / LLM Client
  36. |
  37. | MCP Protocol (stdio or HTTP)
  38. v
  39. main.py (MCP Server)
  40. |
  41. | HTTP requests (localhost:48884)
  42. v
  43. pyRevit Routes (REST API running inside Revit)
  44. |
  45. | Revit API calls
  46. v
  47. Revit Application
  48. ```
  49. **`main.py`** is the MCP server. It speaks the MCP protocol so that Claude (or any MCP-compatible client) can call tools. When a tool is called, `main.py` translates it into an HTTP request and forwards it to Revit.
  50. **pyRevit Routes** is a lightweight REST API that runs *inside* the Revit process. It receives those HTTP requests, executes Revit API code (since it has direct access to the running instance), and returns JSON responses.
  51. They never conflict because they serve different roles, speak different protocols, and listen on different ports.
  52. > **Note:** The Launch & Document tools (`launch_revit`, `list_revit_installations`) are the exception — they run entirely on the MCP side, using `subprocess` to start Revit and then polling the pyRevit Routes health endpoint until the bridge is ready.
  53. 1. **MCP Server (`main.py`)**:
  54. - Built with FastMCP
  55. - Handles HTTP communication with Revit Routes API
  56. - Registers tools from modular tool system
  57. - Provides helper functions for GET/POST/Image requests
  58. 2. **pyRevit Extension (`revit-mcp-python.extension/`)**:
  59. - Contains the Routes API that runs inside Revit
  60. - Modular route registration in `startup.py`
  61. - Individual route modules in `revit_mcp/` directory
  62. 3. **Tool Registration System (`tools/`)**:
  63. - Modular tool organization by functionality
  64. - Central registration through `tools/__init__.py`
  65. - Each module registers its own tools with the MCP server
  66. ---
  67. ## **Supported Tools**
  68. ### **Current Implementation Status**
  69. | Tool Name | Status | Category | Description |
  70. |-----------|--------|----------|-------------|
  71. | `get_revit_status` | ✅ Implemented | Status & Connectivity | Check if the Revit-MCP API is active and responding |
  72. | `get_revit_model_info` | ✅ Implemented | Model Information | Get comprehensive information about the current Revit model |
  73. | `list_levels` | ✅ Implemented | Model Information | Get all levels with elevation information |
  74. | `get_revit_view` | ✅ Implemented | View & Image | Export a specific Revit view as an image |
  75. | `list_revit_views` | ✅ Implemented | View & Image | Get a list of all exportable views organized by type |
  76. | `place_family` | ✅ Implemented | Family & Placement | Place a family instance at specified location with custom properties |
  77. | `list_families` | ✅ Implemented | Family & Placement | Get a flat list of available family types (with filtering) |
  78. | `list_family_categories` | ✅ Implemented | Family & Placement | Get a list of all family categories in the model |
  79. | `get_current_view_info` | ✅ Implemented | View Information | Get detailed information about the currently active view |
  80. | `get_current_view_elements` | ✅ Implemented | View Information | Get all elements visible in the current view |
  81. | `create_point_based_element` | 🔄 Pending | Element Creation | Create point-based elements (doors, windows, furniture) |
  82. | `color_splash` | ✅ Implemented | Visualization | Color elements based on parameter values |
  83. | `clear_colors` | ✅ Implemented | Visualization | Remove view color overrides |
  84. | `list_category_parameters` | ✅ Implemented | Visualization | List category parameters and sample values |
  85. | `execute_revit_code` | ✅ Implemented | Code Execution | Execute IronPython code directly in Revit context |
  86. | `list_revit_installations` | ✅ Implemented | Launch & Document | Discover all Revit versions installed on the system |
  87. | `launch_revit` | ✅ Implemented | Launch & Document | Launch Revit, optionally with a file, and poll for readiness |
  88. | `open_document` | ✅ Implemented | Launch & Document | Open a document in running Revit (supports detach and audit) |
  89. | `close_document` | ✅ Implemented | Launch & Document | Close the active document |
  90. | `save_document` | ✅ Implemented | Launch & Document | Save or Save As the active document |
  91. | `sync_with_central` | ✅ Implemented | Launch & Document | Synchronize a workshared document with central |
  92. | `get_selected_elements` | 🔄 Pending | Selection Management | Get information about currently selected elements |
  93. | `create_line_based_element` | 🔄 Pending | Element Creation | Create line-based elements (walls, beams, pipes) |
  94. | `create_surface_based_element` | 🔄 Pending | Element Creation | Create surface-based elements (floors, ceilings) |
  95. | `delete_elements` | 🔄 Pending | Element Management | Delete specified elements from the model |
  96. | `modify_element` | 🔄 Pending | Element Management | Modify element properties (instance parameters) |
  97. | `reset_model` | 🔄 Pending | Element Management | Reset model by deleting process model elements |
  98. | `tag_walls` | 🔄 Pending | Annotation | Tag all walls in the current view |
  99. | `search_modules` | 🔄 Pending | Integration | Search for available modules/addins |
  100. | `use_module` | 🔄 Pending | Integration | Execute functionality from external modules |
  101. ![Claude listing model elements in the Desktop interface](images/list_model_tool.png)
  102. ![Claude getting a view in the Desktop interface](images/get_view_tool.png)
  103. ## Getting Started
  104. ### Installing uv:
  105. > Refer to ./README_UV.md
  106. ## Installing the Extension on Revit
  107. ### Activate pyRevit Routes
  108. 1. In Revit, navigate to the pyRevit tab
  109. 2. Open Settings
  110. 3. Go to `Routes` > activate `Routes Server`
  111. pyRevit will start listening on port `http://localhost:48884/`
  112. ### Install from pyRevit:
  113. 1. In Revit, navigate to the pyRevit tab
  114. 2. Open Extensions
  115. 3. Select the MCP Server for Revit Python Extension > Install extension
  116. 4. Select location, default is `%APPDATA%\Roaming\pyRevit\Extensions`
  117. 5. Enable and wait for pyRevit to reload. Restart Revit if necessary.
  118. ### Manual Installation on a custom directory:
  119. 1. Clone the repo in a custom location:
  120. ```bash
  121. git clone https://github.com/mcp-servers-for-revit/mcp-server-for-revit-python
  122. ```
  123. 2. Add `.extension` to the root folder name
  124. 3. In Revit, navigate to the pyRevit tab
  125. 4. Open Settings
  126. 5. Under "Custom Extensions", add the path to the `.extension` folder
  127. 6. Save settings and reload pyRevit (you might need to restart Revit entirely)
  128. ## Testing Your Connection
  129. Once installed, test that the Routes API is working:
  130. 1. Choose **MCP > Bridge > Connect** in Revit, then run this authenticated
  131. check from the exact candidate directory (a browser request has no pairing
  132. header and is denied):
  133. ```bash
  134. uv run --frozen python -c "import anyio; from main import revit_get; print(anyio.run(revit_get, '/status/'))"
  135. ```
  136. 2. If successful, you should see a response like:
  137. ```json
  138. {"status": "active",
  139. "health": "healthy",
  140. "revit_available": true,
  141. "document_title": "your_revit_filename",
  142. "api_name": "revit_mcp"}
  143. ```
  144. The Routes Service will now load automatically whenever you start Revit. To disable it, simply remove the extension path from the pyRevit settings.
  145. ## Using the MCP Client
  146. ### Testing with the MCP Inspector
  147. The MCP SDK includes a handy inspector tool for debugging:
  148. ```bash
  149. mcp dev main.py
  150. ```
  151. Then access `http://127.0.0.1:6274` in your browser to test your MCP server interactively.
  152. ### Transport Modes
  153. The MCP server supports multiple transport modes for different use cases:
  154. | Flag | Transport | Endpoints | Use Case |
  155. |------|-----------|-----------|----------|
  156. | (none) | stdio | stdin/stdout | Claude Desktop / Claude Code default |
  157. | `--sse` | SSE only | `/sse`, `/messages/` | Legacy clients |
  158. | `--streamable-http` | HTTP only | `/mcp` | Modern HTTP clients |
  159. | `--combined` | Both | All above | Maximum compatibility |
  160. **Running with combined transport (recommended for HTTP):**
  161. ```bash
  162. uv run --frozen main.py --combined
  163. ```
  164. After pairing, this starts the authenticated server on `http://127.0.0.1:8000` with both SSE and streamable-HTTP endpoints available.
  165. The following unpaired requests return HTTP 401. HTTP clients must include the header returned by `revit_mcp.pairing.authorization_headers()`; prefer stdio to avoid copying a secret into client configuration.
  166. **Testing the endpoints:**
  167. ```bash
  168. # Test streamable-http
  169. curl -X POST http://localhost:8000/mcp
  170. # Test SSE
  171. curl http://localhost:8000/sse
  172. ```
  173. ### Connecting to Claude Desktop
  174. The simplest way to install your MCP server in Claude Desktop:
  175. ```bash
  176. mcp install main.py
  177. ```
  178. Or for manual installation:
  179. 1. Open Claude Desktop → Settings → Developer → Edit Config
  180. 2. Add this to the `mcpServers` section:
  181. ```json
  182. {
  183. "mcpServers": {
  184. "Revit Connector": {
  185. "command": "uv",
  186. "args": [
  187. "run",
  188. "--frozen",
  189. "mcp",
  190. "run",
  191. "/absolute/path/to/main.py"
  192. ]
  193. }
  194. }
  195. }
  196. ```
  197. For HTTP transport mode, the following URL-only example must also be accompanied by the paired Authorization header in a client that supports it:
  198. ```json
  199. {
  200. "mcpServers": {
  201. "Revit Connector": {
  202. "url": "http://localhost:8000/mcp"
  203. }
  204. }
  205. }
  206. ```
  207. ### Connecting to Claude Code
  208. ```bash
  209. claude mcp add -s user "Revit-Connector" -- uv run --frozen mcp run /absolute/path/to/main.py
  210. ```
  211. # Creating Your Own Tools
  212. The modular architecture of this project makes adding functionalities relatively simple. The provided LLM.txt file also gives your language model the necessary context to get started right away.
  213. The process involves three main parts:
  214. ## Part 1: Create the Route Module in Revit
  215. Create a new Python file within the `revit-mcp-python.extension/revit_mcp/` directory (e.g., `revit_mcp/your_module.py`). This module will contain all the related functions you want to expose.
  216. ```python
  217. # In revit-mcp-python.extension/revit_mcp/your_module.py
  218. # -*- coding: UTF-8 -*-
  219. """
  220. Your Module for Revit MCP
  221. Handles your specific functionality.
  222. """
  223. from pyrevit import routes, revit, DB
  224. import json
  225. import logging
  226. # Standard logger setup
  227. logger = logging.getLogger(__name__)
  228. def register_your_routes(api):
  229. """Register all your routes with the API."""
  230. # ---- Example 1: A GET request for reading data ----
  231. @api.route('/your_endpoint/', methods=["GET"])
  232. def get_project_title(doc):
  233. """Gets the project title from the Revit model."""
  234. try:
  235. value = doc.Title
  236. return routes.make_response(data={"status": "success", "data": value})
  237. except Exception as e:
  238. logger.error("Get project title failed: {}".format(str(e)))
  239. return routes.make_response(data={"error": str(e)}, status=500)
  240. # ---- Example 2: A POST request for modifying the model ----
  241. @api.route('/modify_model/', methods=["POST"])
  242. def modify_model(doc, request):
  243. """Handles POST requests for modifying the Revit model."""
  244. try:
  245. data = json.loads(request.data) if isinstance(request.data, str) else request.data
  246. # Use a transaction for all model modifications
  247. t = DB.Transaction(doc, "Modify Model via MCP")
  248. t.Start()
  249. try:
  250. element_id = data.get("element_id")
  251. new_value = data.get("new_value")
  252. element = doc.GetElement(DB.ElementId(int(element_id)))
  253. param = element.LookupParameter("Comments")
  254. param.Set(new_value)
  255. t.Commit()
  256. return routes.make_response(data={"status": "success", "result": "Element modified."})
  257. except Exception as tx_error:
  258. if t.HasStarted() and not t.HasEnded():
  259. t.RollBack()
  260. raise tx_error
  261. except Exception as e:
  262. logger.error("Modify model failed: {}".format(str(e)))
  263. return routes.make_response(data={"error": str(e)}, status=500)
  264. logger.info("Your custom routes were registered successfully.")
  265. ```
  266. ## Part 2: Create the MCP Tool Module
  267. Create the corresponding tools for the MCP server in the `tools/` directory (e.g., `tools/your_tools.py`). This module will use the `revit_get` and `revit_post` helpers from `main.py`.
  268. ```python
  269. # In tools/your_tools.py
  270. # -*- coding: utf-8 -*-
  271. """Your tools for the MCP server."""
  272. from mcp.server.fastmcp import Context
  273. from .utils import format_response
  274. def register_your_tools(mcp, revit_get, revit_post, revit_image=None):
  275. """Register your tools with the MCP server."""
  276. # ---- Tool for the GET request ----
  277. @mcp.tool()
  278. async def get_revit_project_title(ctx: Context) -> str:
  279. """
  280. Retrieves the title of the currently open Revit project.
  281. """
  282. response = await revit_get("/your_endpoint/", ctx)
  283. return format_response(response)
  284. # ---- Tool for the POST request ----
  285. @mcp.tool()
  286. async def modify_revit_element_comment(
  287. element_id: int,
  288. new_value: str,
  289. ctx: Context = None
  290. ) -> str:
  291. """
  292. Modifies the 'Comments' parameter of a specific element.
  293. Args:
  294. element_id: The ID of the element to modify.
  295. new_value: The new comment to apply to the element.
  296. """
  297. payload = {"element_id": element_id, "new_value": new_value}
  298. response = await revit_post("/modify_model/", payload, ctx)
  299. return format_response(response)
  300. ```
  301. ## Part 3: Register Your New Modules
  302. ### 1. Register the Route Module
  303. Open `revit-mcp-python.extension/startup.py` and add your new route registration function.
  304. ```python
  305. # In revit-mcp-python.extension/startup.py
  306. # ... (other imports)
  307. # Import the registration function from your new module
  308. from revit_mcp.your_module import register_your_routes
  309. def register_routes():
  310. """Register all MCP route modules"""
  311. api = routes.API('revit_mcp')
  312. try:
  313. # ... (existing route registrations)
  314. # Register your new routes (this registers all functions inside)
  315. register_your_routes(api)
  316. logger.info("All MCP routes registered successfully")
  317. except Exception as e:
  318. logger.error("Failed to register MCP routes: {}".format(str(e)))
  319. raise
  320. ```
  321. ### 2. Register the Tool Module
  322. Open `tools/__init__.py` and add your new tool registration function.
  323. ```python
  324. # In tools/__init__.py
  325. # ... (other tool imports)
  326. # Import the registration function from your new tool module
  327. from .your_tools import register_your_tools
  328. def register_tools(mcp_server, revit_get_func, revit_post_func, revit_image_func):
  329. """Register all tools with the MCP server"""
  330. # ... (existing tool registrations)
  331. # Register your new tools (this registers all tools inside)
  332. register_your_tools(mcp_server, revit_get_func, revit_post_func, revit_image_func)
  333. return mcp_server
  334. ```
  335. ## Roadmap
  336. This is a work in progress and more of a demonstration than a fully-featured product. Future improvements could include:
  337. - **Creating a Client inside Revit**
  338. - **Implementing compatibilities with other language Models**
  339. - **Authentication and security enhancements**
  340. - **More advanced Revit tools and capabilities**
  341. - **Better error handling and debugging features**
  342. - **Benchmarking with local models**
  343. - **Documentation and examples for common use cases**
  344. - **...**
  345. ## Contributing
  346. Contributions are welcome! Feel free to submit pull requests or open issues for any bugs or feature requests.
  347. Feel free to reach out to me if you have any questions, ideas

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.