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) 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).