Content
# acad-mcp (private)
MCP server giving Claude full control of Autodesk AutoCAD 2027 via an in-process
PyRx bridge. Companion to the Revit MCP (same architecture; Revit uses :48884,
AutoCAD uses :48885).
## Architecture
Claude (stdio/HTTP/SSE) -> FastMCP server (server/) -> HTTP 127.0.0.1:48885
-> PyRx plugin inside AutoCAD (plugin/) -> main-thread pump -> document lock
-> ObjectARX via PyRx.
The plugin runs a `ThreadingHTTPServer` on a worker thread; each request is
handed off via a `queue` to a `wx.Timer` running on AutoCAD's main thread (the
pump), which drains the queue, locks the document, and runs the handler. This
timer-pump design replaced direct `wx.CallAfter` posting, which dropped events
on some boots. Start the pump with `ACADMCP_START` in an AutoCAD session.
## Claude plugin
The Claude plugin packaging (marketplace, manifest, autocad-drafting skill,
slash commands, setup script, bundled server snapshot) lives in the companion
repo [acad-mcp-plugin](https://github.com/Demolinator/acad-mcp-plugin) -
install with `/plugin marketplace add Demolinator/acad-mcp-plugin` then
`/plugin install autocad@acad-mcp-plugin`. This repo is where server/plugin
development happens; refresh the bundled snapshot over there with its
`sync-server.ps1`.
## Setup from scratch (developer / standalone server)
> Most people should install the **plugin** instead — see
> [acad-mcp-plugin](https://github.com/Demolinator/acad-mcp-plugin), which bundles
> this server and is one click. Use the steps below if you're developing the
> server or wiring it up standalone (without the plugin).
**Prerequisites:** AutoCAD 2027 (full, not LT), Python 3.12 (64-bit), and Claude
Code or Claude Desktop. On Windows: `winget install Python.Python.3.12`.
1. **Clone and create the environment:**
```
git clone https://github.com/Demolinator/acad-mcp
cd acad-mcp
py -3.12 -m venv .venv
.venv\Scripts\python -m pip install -e ".[dev]"
```
2. **Install the PyRx bridge into the Python that AutoCAD will use:**
```
py -3.12 -m pip install cad-pyrx
```
3. **Run the one-time prep script** — `setup-acad-mcp.bat` (at the repo root).
It writes `%APPDATA%\pyrx\pyrx.toml` (pointing PyRx at this repo's
`plugin\acad_mcp_plugin.py`) and `C:\temp\acadmcp_boot.scr`, and is
idempotent. (Or do it by hand: set `pyrx.toml`'s `onload_path` to the plugin
file.)
4. **Start AutoCAD with the listener:**
```
"C:\Program Files\Autodesk\AutoCAD 2027\acad.exe" /nologo /b C:\temp\acadmcp_boot.scr
```
(Or start AutoCAD normally and run `ACADMCP_START` once PyRx has loaded.)
The bridge now listens on `http://127.0.0.1:48885`.
5. **Register the MCP server with Claude:**
```
claude mcp add acad -- <repo>\.venv\Scripts\python.exe -m acad_mcp_server.main
```
(Claude Desktop/Cowork: add the same `command`/`args` under `mcpServers` in
`%APPDATA%\Claude\claude_desktop_config.json`.)
6. **Verify:** in Claude, call `acad_status` — expect `connected: true`.
## Daily use
Start AutoCAD (plugin auto-loads; run ACADMCP_START if the boot script wasn't used).
In Claude: `acad_status` checks connectivity.
**41 MCP tools** (39 bridged to AutoCAD + `acad_status` + `capture_screen`; the
two non-bridged tools run server-side, so the plugin's `/health` tools list
reports 39). The bridged tools:
- **Create:** draw_line, draw_circle, draw_polyline, draw_rectangle, draw_arc,
draw_text
- **Layers / query:** create_layer, list_layers, get_drawing_info, get_entity,
list_entities
- **Modify:** move_entities, copy_entities, rotate_entities, erase_entities,
set_entity_properties
- **Document / escape hatch:** save_drawing, execute_python
### Drawing documentation (Phase 2A)
Everything needed to turn geometry into a complete, annotated, plottable sheet:
- **Dimensions:** dim_linear, dim_aligned, dim_radial (radial *and* diametric),
dim_angular
- **Hatch + multileader:** add_hatch (predefined patterns on a closed boundary),
add_leader
- **Blocks + attributes:** define_block, insert_block, list_blocks,
set_block_attributes
- **Xrefs:** attach_xref, list_xrefs, detach_xref
- **Text / dim styles:** create_text_style, create_dim_style, list_styles
- **Layouts + viewports:** create_layout, create_viewport, list_layouts
- **Title blocks + plotting:** insert_title_block, plot_to_pdf (via the
DWG To PDF.pc3 device, returns the written PDF path)
## Tests
- Unit (no AutoCAD): `.venv\Scripts\python -m pytest` (70 tests)
- Live smoke (AutoCAD running): `.venv\Scripts\python smoke\smoke_test.py`
## Layout
- `server/` FastMCP server (stdio default; --http/--sse)
- `plugin/` PyRx plugin loaded inside AutoCAD (HTTP :48885)
- `smoke/` live end-to-end test
- `docs/superpowers/` spec and plans
## Known dev-machine state (outside repo)
- `%APPDATA%\pyrx\pyrx.toml` onload_path -> this repo's plugin
- `C:\temp\acadmcp_boot.scr` sets SECURELOAD=0 (dev only) and starts the listener
## License
MIT — see [LICENSE](LICENSE). Copyright (c) 2026 Talal Ahmed.
(The companion [acad-mcp-plugin](https://github.com/Demolinator/acad-mcp-plugin)
that packages this server is licensed Apache-2.0.)
