# Understanding the revit-mcp and revit-mcp-plugin Relationship: Server-Add-in Architecture > Explore the revit-mcp server and revit-mcp-plugin add-in relationship. Discover how they create a client-server bridge for AI tool integration in Revit via TCP socket communication. - Repository: [MCP servers for Revit/revit-mcp](https://github.com/mcp-servers-for-revit/revit-mcp) - Tags: architecture - Published: 2026-02-16 --- **The revit-mcp repository provides the MCP server that runs outside Revit, while revit-mcp-plugin is the Revit add-in that executes inside Revit; together they form a client-server bridge that translates AI tool calls into Revit API commands via TCP socket communication.** The `mcp-servers-for-revit/revit-mcp` repository implements a Model Context Protocol (MCP) server that exposes Revit functionality to AI assistants. Understanding the relationship between revit-mcp and revit-mcp-plugin is essential for architects and developers building automated workflows, as these two components must run simultaneously to enable AI-driven Revit automation. ## What is revit-mcp? The MCP Server Component `revit-mcp` is the **MCP server** that operates as a standalone Node.js/TypeScript process outside of the Revit environment. Its primary responsibilities include: - **Tool Registration**: Dynamically registering MCP tools such as `get_current_view_info`, `send_code_to_revit`, and `get_selected_elements` via [`src/tools/register.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/tools/register.ts) - **Server Initialization**: Creating an `McpServer` instance and connecting transport layers in [`src/index.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/index.ts) - **Connection Management**: Maintaining TCP socket connections to the Revit plugin through [`src/utils/ConnectionManager.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/utils/ConnectionManager.ts) and [`src/utils/SocketClient.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/utils/SocketClient.ts) The server acts as the intermediary between AI assistants (clients) and the Revit application, translating natural language requests into structured JSON-RPC commands. ## What is revit-mcp-plugin? The Revit Add-in Component `revit-mcp-plugin` is the **Revit add-in** (plugin) that runs **inside** the Revit process as a compiled .NET assembly. This component provides the execution environment for Revit API calls and includes: - **SocketService**: A TCP listener service that accepts connections on `localhost:8080` (configurable) - **CommandManager**: Routes incoming JSON-RPC requests to appropriate command handlers - **CommandExecute**: Executes the actual Revit API calls within the Revit context (e.g., creating walls, modifying elements, retrieving view data) Because Revit uses a single-threaded apartment (STA) model for API access, the plugin must marshal all API calls to Revit's main thread, making the in-process add-in architecture necessary for safe Revit automation. ## How revit-mcp and revit-mcp-plugin Communicate The relationship between revit-mcp and revit-mcp-plugin relies on a **TCP socket-based JSON-RPC protocol** that enables bidirectional communication between the external server and the internal Revit process. ### Connection Management and SocketClient In [`src/utils/ConnectionManager.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/utils/ConnectionManager.ts), the server implements a connection wrapper that manages the lifecycle of the TCP connection: ```typescript // src/utils/ConnectionManager.ts (simplified) import { RevitClientConnection } from './SocketClient.js'; export async function withRevitConnection( callback: (client: RevitClientConnection) => Promise ): Promise { const client = new RevitClientConnection('localhost', 8080); try { await client.connect(); return await callback(client); } finally { await client.disconnect(); } } ``` The [`SocketClient.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/SocketClient.ts) file implements the actual JSON-RPC client that serializes requests and deserializes responses: ```typescript // src/utils/SocketClient.ts (conceptual) export class RevitClientConnection { private socket: net.Socket; private pendingRequests: Map> = new Map(); async sendCommand(method: string, params?: any): Promise { const id = generateRequestId(); const request = { jsonrpc: "2.0", method: method, params: params || {}, id: id }; this.socket.write(JSON.stringify(request) + '\n'); // Wait for response with matching ID return this.pendingRequests.get(id).promise; } } ``` ### JSON-RPC Protocol Implementation When an AI assistant invokes a tool, the server sends a JSON-RPC 2.0 request to the plugin: ```json { "jsonrpc": "2.0", "method": "get_current_view_info", "params": {}, "id": "1697845123456" } ``` The plugin's `CommandManager` routes this to the appropriate handler, executes the Revit API call, and returns: ```json { "jsonrpc": "2.0", "result": { "viewName": "Level 1", "viewType": "FloorPlan", "id": 123456 }, "id": "1697845123456" } ``` ## Code Flow: From AI Tool Call to Revit API Execution Understanding the complete relationship between revit-mcp and revit-mcp-plugin requires tracing the execution path from tool registration to API execution. ### Tool Registration on the Server In [`src/tools/register.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/tools/register.ts), the server dynamically imports and registers all available tools: ```typescript // src/tools/register.ts import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { registerGetCurrentViewInfoTool } from "./get_current_view_info.js"; import { registerSendCodeToRevitTool } from "./send_code_to_revit.js"; export function registerTools(server: McpServer) { registerGetCurrentViewInfoTool(server); registerSendCodeToRevitTool(server); // ... other tools } ``` ### Tool Implementation with Connection Handling The `get_current_view_info` tool demonstrates how the server uses `withRevitConnection` to communicate with the plugin: ```typescript // src/tools/get_current_view_info.ts (simplified) import { z } from "zod"; import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { withRevitConnection } from "../utils/ConnectionManager.js"; export function registerGetCurrentViewInfoTool(server: McpServer) { server.tool( "get_current_view_info", "Get current view info", {}, // schema async (_args, _extra) => { const result = await withRevitConnection(async client => { return await client.sendCommand("get_current_view_info"); }); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }; } ); } ``` ### Dynamic Code Execution Tool The `send_code_to_revit` tool allows AI assistants to execute arbitrary C# code within Revit: ```typescript // src/tools/send_code_to_revit.ts (conceptual) server.tool( "send_code_to_revit", "Send C# code to execute in Revit", { code: z.string().describe("C# code to execute"), parameters: z.array(z.any()).optional() }, async (args, _extra) => { return await withRevitConnection(async client => { return await client.sendCommand("execute_code", { code: args.code, parameters: args.parameters || [] }); }); } ); ``` ## Key Files and Implementation Details The relationship between revit-mcp and revit-mcp-plugin is implemented through specific files in both repositories: | File | Component | Purpose | |------|-----------|---------| | [`src/index.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/index.ts) | revit-mcp | Entry point that creates `McpServer` and initializes the transport | | [`src/tools/register.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/tools/register.ts) | revit-mcp | Dynamically imports and registers all MCP tools | | [`src/utils/ConnectionManager.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/utils/ConnectionManager.ts) | revit-mcp | Manages TCP connection lifecycle to the plugin | | [`src/utils/SocketClient.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/utils/SocketClient.ts) | revit-mcp | Implements JSON-RPC client protocol over TCP sockets | | [`src/tools/send_code_to_revit.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/tools/send_code_to_revit.ts) | revit-mcp | Tool implementation for dynamic C# code execution | | `SocketService` | revit-mcp-plugin | TCP listener service running inside Revit | | `CommandManager` | revit-mcp-plugin | Routes incoming commands to appropriate handlers | | `CommandExecute` | revit-mcp-plugin | Executes Revit API calls within the Revit process context | According to the README in the revit-mcp repository, the server "is the server side (providing Tools to AI), and you need to use **revit-mcp-plugin** (driving Revit) in conjunction." ## Summary - **revit-mcp** is the external MCP server that registers AI tools and manages protocol communication; it runs as a standalone Node.js process. - **revit-mcp-plugin** is the internal Revit add-in that executes within the Revit process, hosting a TCP socket service to receive and execute commands. - The two components communicate via **JSON-RPC over TCP** (default port 8080), with `ConnectionManager` and `SocketClient` handling the client side and the plugin's `SocketService` handling the server side. - **Tool registration** occurs in [`src/tools/register.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/tools/register.ts), while actual Revit API execution happens inside the plugin's `CommandExecute` component, ensuring thread-safe access to Revit's single-threaded API. ## Frequently Asked Questions ### Does revit-mcp work without revit-mcp-plugin installed? No. The revit-mcp server cannot execute any Revit operations without the plugin running inside Revit. When you invoke tools like `get_current_view_info` or `send_code_to_revit`, the server attempts to connect to `localhost:8080` where the plugin's `SocketService` listens. If the plugin is not loaded in Revit, the connection fails and the tool returns an error indicating that Revit is not accessible. ### Can I run multiple instances of revit-mcp connecting to different Revit sessions? Currently, the architecture supports one active connection per revit-mcp server instance because `ConnectionManager` maintains a single `RevitClientConnection` to `localhost:8080`. To control multiple Revit sessions simultaneously, you would need to run separate revit-mcp server instances configured to connect to different TCP ports, with each Revit instance running a plugin instance listening on the corresponding port. ### What protocol do revit-mcp and revit-mcp-plugin use to communicate? The components communicate using **JSON-RPC 2.0** over raw TCP sockets. The [`SocketClient.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/SocketClient.ts) implementation in revit-mcp serializes requests with `jsonrpc`, `method`, `params`, and `id` fields, while the plugin's `CommandManager` deserializes these requests, routes them to `CommandExecute`, and returns JSON-RPC response objects containing either a `result` or `error` field. ### Is the revit-mcp-plugin code available in the same repository? No. The `revit-mcp-plugin` is maintained as a separate repository. The `revit-mcp` repository (the one analyzed here) contains only the server-side TypeScript code. According to the README, users must download and install the `revit-mcp-plugin` separately, build it as a Revit add-in, and load it into Revit before starting the revit-mcp server.