altium-mcp

name: altium-mcp description: Uses the altium-mcp Model Context Protocol server to read and edit PCB/schematic data from Altium Designer via a DelphiScript bridge on Windows. Apply when the user enables the altium-mcp MCP server, mentions Altium Designer, X2.EXE, PCB layers/rules/nets, schematic components, designators, schematic edits, workspace projects, or MCP tools get_server_status, altium_ping, get_schematic_data, edit_schematic, get_pcb_*, get_all_designators, get_component_pins.

Altium MCP

Portable use

• MCP instructions: Compliant clients load server guidance automatically when the MCP session starts (no skill file required for that part).
• Cursor Agent Skills: Copy this folder to the client machine (see INSTALL.md here), or run altium-mcp-install-skill after installing the package.

Scope

This skill documents the published altium-mcp server: Node orchestration plus DelphiScript bundled as altium-scripts/ in the package (copied at runtime into the workspace AltiumScript/ directory).

Architecture (short)

1. MCP server (Node) registers tools and, on each live call, acquires a workspace file lock, syncs bundled scripts into AltiumScript/, writes request.json, and spawns X2.EXE with -RScriptingSystem:RunScript(ProjectName="<workspace>\\AltiumScript\\Altium_API.PrjScr"|ProcName="Altium_API>Run").
2. DelphiScript (Altium_API.pas in the bundle) reads request.json, runs the command, writes response.json (success, result, error).
3. Workspace root: env ALTIUM_MCP_WORKSPACE, else workspaceRoot in ~/.altium-mcp/config.json (Windows: %USERPROFILE%\.altium-mcp\config.json), else ~/.altium-mcp/workspace.
4. Altium EXE: env ALTIUM_MCP_ALTIUM_EXE, else altiumExePath in that config file, else newest AD*\X2.EXE under C:\Program Files\Altium.

Where tool documentation lives

• src/toolDefinitions.ts — Canonical long descriptions (Purpose, When to use, Parameters, Returns, Prerequisites, Errors). Edit here first.
• src/index.ts — Registers tools with those descriptions and MCP ToolAnnotations (read-only hints for most tools).
• MCP instructions — src/mcpInstructions.ts: short workflow + table; clients receive this at initialize.
• This file — Human/agent skill; keep in sync when adding or renaming tools.

Agent workflow

1. get_server_status — Confirm altiumExeFound, scriptProjectFound, paths. Stop and fix setup if false.
2. configure_altium_exe — Only if exe path is wrong or missing; path must exist on disk.
3. altium_ping — Expect JSON with pong / protocol version inside result from the bridge.
4. Data tools — Follow document focus rules below.

Tool reference (summary)

Document focus (Altium UI)

Tell the user to open and focus the correct .PcbDoc when PCB tools return empty or errors.

MCP tools ↔ bridge commands

get_schematic_data parameters

• schematic_full_path: absolute .SchDoc path for an open project (preferred when several projects are open; / or \\ accepted).
• Or project_full_path + optional schematic_sheet_file_name (file name only).
• Omit both path forms to use focused project (optional sheet filter).
• include_queries (optional string array): omit for legacy JSON { "components": [...], "drawing_objects": [...] } only. If set, response is filtered: schematic_data_mode, include_queries echo, and only requested buckets (e.g. sheet → sheets[] with size/grids; wires, buses, components, …). Use [ "all" ] for every split bucket. Tokens: all | sheet | components | wires | buses | net_labels | power_ports | text_labels | junctions | ports | off_sheet_connectors | sheet_symbols | directives | figures | harness (empty [] placeholder) | drawing_objects (combined list like legacy). Invalid-only tokens fall back to legacy mode.

Legacy return: components include library parameters; drawing_objects lists wires, buses, net labels, graphics, etc. Sheet title-block document parameters are excluded. Not pins inside components.

edit_schematic (summary)

Single MCP tool; action selects mode: set_component_transform, set_component_parameters, place_component, add_text, add_net_label, add_wire, plus WIRES phase-1: place_wire (alias of add_wire), place_net_label (alias of add_net_label), add_bus (same CSV as wire), add_bus_entry (exactly four numbers in wire_points_csv); POWER phase-2: place_power_port (requires power_port_style), place_gnd / place_vcc (shortcuts with defaults in the bridge). Requires schematic_full_path or schematic_sheet_file_name (same resolution idea as get_schematic_data). Does not auto-save in Altium. Verify with get_schematic_data after edits.

Troubleshooting TIMEOUT / script “frozen”

• Breakpoints in Altium Script: If you run the MCP bridge scripts with the DelphiScript debugger and execution hits a breakpoint, Altium stops until you Continue. No response.json is written, so MCP reports TIMEOUT. Fix: remove breakpoints in the script project, use Run without debugging, or Stop Debugging / Continue so the script finishes.
• Lock file: After an abandoned run, if tools fail with lock errors, delete .bridge.lock in the MCP workspace directory (get_server_status shows workspaceRoot).
• edit_schematic uses a longer MCP wait (240s) than other tools; first Altium launch after idle can still be slow.
• Bridge errors for the agent: On success: false, Altium writes bridge_last_error.txt in the workspace; live tools merge that file into the returned error string. Compile-time script errors never reach the bridge: paste Altium Messages into bridge_user_reported_error.txt in the same folder, then get_server_status exposes bridgeUserReportedError / bridgeLastError.

Interpreting results

• Tool return shape is MCP text content with JSON (pretty-printed objects).
• Bridge: { "success": true, "result": ... } or success: false with error.
• Node launch/path errors: AD_NOT_FOUND, SCRIPT_PROJECT_NOT_FOUND, ALT_LAUNCH_FAILED, TIMEOUT, INVALID_BRIDGE_RESPONSE, RESPONSE_READ_FAILED.
• Serialized access: .bridge.lock under workspace; long Altium operations can block other tools (~default 120s command timeout, ~60s lock wait).

Delphi commands not yet MCP-exposed

The bridge script may implement additional commands (e.g. move_components, create_net_class, take_view_screenshot, output job helpers) beyond the MCP tools listed in the tables above.

Authors (source repository)

When changing tools or bridge behavior: update src/toolDefinitions.ts, then src/mcpInstructions.ts and this SKILL.md. Run npm run build (syncs this skill into .cursor/skills/ when scripts/sync-cursor-skill.mjs runs).