allplan-mcp-bridge

A production-grade MCP server that exposes Allplan's BIM API (geometry, attributes, IFC import/export, and layer management) to MCP clients such as Claude Code and Claude Desktop. Runs as a normal Python process that communicates with a PythonPart agent embedded inside Allplan over local TCP, so Claude can create, query, and modify BIM elements while every operation stays inside Allplan's native undo history.

---

Quick start

Prerequisites

Component	Version
Allplan	2026 (tested), likely works on 2025 / 2024-1
OS	Windows 10 / 11
Python (external)	3.12+
uv	pip install uv
Claude Code or Claude Desktop	Latest

1 — Clone and install the MCP server

git clone https://github.com/andrej-reeg/allplan-mcp-bridge.git
cd allplan-mcp-bridge
uv sync

2 — Install the Allplan PythonPart

python scripts\install_pythonpart.py

Auto-detects the Allplan 2026 PythonParts directory. Pass --scripts-dir and --library-dir explicitly if auto-detection fails.

3 — Activate the bridge in Allplan

1. Launch Allplan 2026 and open any project.
2. In the Library, find Allplan MCP Bridge → AllplanMcpBridge and activate it.
3. A palette should appear. The bridge is now listening on TCP port 49152.

4 — Start the MCP server

uv run python -m allplan_mcp_server

You should see {"event": "ipc.connected", ...} in the log. If not, check that the Allplan palette is visible and the bridge is active.

5 — Configure Claude Code (or Claude Desktop)

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "allplan": {
      "command": "uv",
      "args": ["run", "python", "-m", "allplan_mcp_server"],
      "cwd": "C:\\path\\to\\allplan-mcp-bridge"
    }
  }
}

Then ask Claude:

"Create a 5 m wall at (0,0,0) to (5000,0,0), height 3000 mm, thickness 300 mm."

The wall should appear in Allplan, inside one undo bracket.

---

Architecture

Claude Code / Desktop
     │  stdio JSON-RPC (MCP protocol)
     ▼
allplan_mcp_server          (this repo — normal Python 3.12 process)
     │  TCP 127.0.0.1:49152  length-prefixed JSON  + HMAC token auth
     ▼
allplan_agent               (PythonPart — runs INSIDE Allplan's embedded Python)
     │  thread-safe queue
     ▼
Allplan main thread → NemAll_Python_* API → BIM document

See docs/architecture.md for the full picture and docs/threading-model.md for the one law that must never be broken.

---

Configuration reference

All settings use the ALLPLAN_MCP_ prefix. Set as environment variables or in a .env file in the repository root.

Variable	Default	Description
ALLPLAN_MCP_IPC_TRANSPORT	tcp	tcp or named_pipe
ALLPLAN_MCP_TCP_HOST	127.0.0.1	TCP host (loopback only)
ALLPLAN_MCP_TCP_PORT	49152	TCP port
ALLPLAN_MCP_ALLPLAN_WORKSPACE_ROOT	auto-detected	Root path for IFC file allowlist
ALLPLAN_MCP_REQUEST_TIMEOUT_SECONDS	10.0	Timeout for standard operations
ALLPLAN_MCP_LONG_OP_TIMEOUT_SECONDS	120.0	Timeout for IFC import/export
ALLPLAN_MCP_LOG_LEVEL	INFO	DEBUG, INFO, WARNING, ERROR
ALLPLAN_MCP_MAX_FRAME_BYTES	16777216	IPC frame size cap (16 MiB)
ALLPLAN_MCP_MAX_ARG_BYTES	1048576	Per-tool argument size cap (1 MiB)

---

Available tools

See docs/tool-catalog.md for the full catalog with input schemas and examples. Short summary:

Category	Tools
Geometry	create_wall, create_slab, create_column, create_beam, get_element, delete_element, move_element
Document	get_active_document_info, save_document, undo, redo
Attributes	get_attributes, set_attributes
Layers	list_layers, create_layer, set_layer_visibility, assign_layer
IFC	export_ifc, import_ifc
Health	health

---

Supported Allplan versions

Version	Status
Allplan 2026	Tested, supported
Allplan 2025	Should work — not formally tested
Allplan 2024-1	Should work — not formally tested
Earlier	Not supported

---

Limitations (v1)

• Single instance. One Allplan + one MCP server. Multi-instance support is out of scope for v1; see docs/architecture.md for the design note.
• Windows only. Allplan is Windows-only. The MCP server can run in WSL2 and connect to Allplan over TCP.
• Geometry only. create_slab, create_column, create_beam create generic 3-D solids (not architectural elements with material assignments). Architecture elements are planned for v2.
• No live preview. Elements are inserted when the bridge processes the command, not on mouse hover.
• IFC size. Exports > 1 GiB are hard-rejected. Exports > 100 MiB log a warning.
• Main-thread serialisation. All Allplan API calls run on the main thread. Heavy operations (large IFC export) will briefly freeze Allplan's UI.

---

Troubleshooting

ipc.connect_failed in MCP server logs

• Confirm the Allplan palette is visible and shows "running".
• Check that the TCP port (default 49152) is not blocked.
• Check ~/.allplan-mcp/bridge.log for errors from the agent.

Wall/element created but in wrong position

• Check ~/.allplan-mcp/debug.log for _wall: attempt N lines — these show which geometry placement strategy succeeded.

PathNotAllowedError on IFC export

• The path is outside ALLPLAN_MCP_ALLPLAN_WORKSPACE_ROOT.
• Either move the file or set the env var to a parent directory.

Timeout errors on get_active_document_info

• This call requires the Allplan main thread and returns {main_thread_required: true} when called from the background pump. Trigger a mouse event in Allplan (move the cursor into the drawing) to process the next tick.

---

Development

uv sync --dev
uv run pytest tests/unit tests/integration
uv run ruff check src tests
uv run mypy src

See CONTRIBUTING.md for how to add a new tool.