| 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)
- 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").
- DelphiScript (
Altium_API.pas in the bundle) reads request.json, runs the command, writes response.json (success, result, error).
- Workspace root: env
ALTIUM_MCP_WORKSPACE, else workspaceRoot in ~/.altium-mcp/config.json (Windows: %USERPROFILE%\.altium-mcp\config.json), else ~/.altium-mcp/workspace.
- 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
- get_server_status — Confirm
altiumExeFound, scriptProjectFound, paths. Stop and fix setup if false.
- configure_altium_exe — Only if exe path is wrong or missing; path must exist on disk.
- altium_ping — Expect JSON with
pong / protocol version inside result from the bridge.
- Data tools — Follow document focus rules below.
Tool reference (summary)
| Tool | Parameters | Returns (typical) | Altium need |
|---|
| get_server_status | — | Paths, exe flags, env | Triggers script sync |
| configure_altium_exe | path | { ok, altiumExePath } | File must exist |
| altium_ping | — | pong in result | AD install |
| get_workspace_projects | — | Projects + logical docs + focused index | AD open |
| get_schematic_data | optional schematic_full_path, project_full_path, schematic_sheet_file_name | { components[], drawing_objects[] } (mils + parameters + primitives) | Project(s) open |
| edit_schematic | action + same sheet targeting as get_schematic_data + mode fields | { action, sheet, details } or Delphi ERROR: | Project(s) open |
| get_pcb_layers | — | Layer metadata | Focused PCB |
| get_pcb_rules | — | Rule list | Focused PCB |
| get_all_nets | — | Net names | Focused PCB |
| get_pcb_layer_stackup | — | Stackup JSON | Focused PCB |
| get_all_designators | — | string[] designators | Focused PCB |
| get_component_pins | designators: string[] | Pin data | Focused PCB |
| file_mode_capabilities | — | Capability flags | None (Node) |
Document focus (Altium UI)
| Situation | Requirement |
|---|
get_workspace_projects, altium_ping, get_schematic_data, edit_schematic | No PCB focus; schematic uses paths or focused project |
get_pcb_layers, get_pcb_rules, get_all_nets, get_pcb_layer_stackup, get_all_designators, get_component_pins | Active/focused PCB in the focused project |
Tell the user to open and focus the correct .PcbDoc when PCB tools return empty or errors.
MCP tools ↔ bridge commands
| MCP tool | Delphi command / notes |
|---|
| altium_ping | ping |
| get_workspace_projects | list_workspace |
| get_schematic_data | get_schematic_data (+ optional path params) |
| edit_schematic | schematic_edit (+ action, paths, mode params) |
| get_pcb_layers | get_pcb_layers |
| get_pcb_rules | get_pcb_rules |
| get_all_nets | get_all_nets |
| get_pcb_layer_stackup | get_pcb_layer_stackup |
| get_all_designators | get_all_component_data (parsed in Node) |
| get_component_pins | get_component_pins + designators array |
| file_mode_capabilities | Node-only (no Altium) |
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).
