Skip to main content
Glama
altium-mcp

altium-mcp

by flaco-source

altium-mcp

Model Context Protocol (MCP) server that connects Cursor (and other MCP clients) to Altium Designer on Windows, so an assistant can query PCB and schematic data and drive DelphiScript automation.

This is a third-party project; it is not affiliated with Altium.

Requirements

Item

Notes

OS

Windows 10/11 (live bridge targets Altium on Windows)

Altium Designer

22+ recommended (X2.EXE)

Node.js

20+

Cursor

MCP over stdio

Related MCP server: easyeda-mcp

Quick start

npm install
npm run build

Configure Cursor using docs/cursor-mcp.md.

First steps in the IDE:

  1. Call MCP tool get_server_status — confirms workspace paths and X2.EXE discovery (and syncs scripts into the workspace AltiumScript/ folder).

  2. If needed, call configure_altium_exe with the full path to X2.EXE.

  3. Call altium_ping to confirm the DelphiScript bridge responds inside Altium.

  4. Use get_workspace_projects to discover open .PrjPcb paths and schematic sheet paths.

  5. PCB: with the target .PcbDoc open and focused in Altium, use get_pcb_layers, get_all_nets, etc.

  6. Schematic: get_schematic_data and edit_schematic do not require an active PCB; pass schematic_full_path or project_full_path + schematic_sheet_file_name. After edits, call get_schematic_data again on the same sheet to verify.

Agent-oriented details (timeouts, lock file, placement hints) are in the MCP server instructions and in skills/altium-mcp/SKILL.md. Schematic edit coverage and notes: docs/edit-schematic-progress.md.

How it works

  • The server writes request.json under the workspace (default %USERPROFILE%\.altium-mcp\workspace).

  • It launches Altium with -RScriptingSystem:RunScript pointing at the bundled Altium_API.PrjScr project.

  • DelphiScript Run reads the request, runs PCB/SCH API calls, and writes response.json.

  • A file lock .bridge.lock serializes concurrent tool calls (longer timeout for edit_schematic).

See docs/architecture.md and JSON schemas in schemas/.

MCP tools (high level)

Tool

Purpose

get_server_status

Paths, env, whether X2.EXE and script project exist; bridge diagnostic snippets

configure_altium_exe

Save X2.EXE path to %USERPROFILE%\.altium-mcp\config.json

altium_ping

Health check via DelphiScript

get_workspace_projects

Open workspace projects and logical documents (paths for SCH/PCB tools)

get_schematic_data

Export schematic sheet data; optional include_queries[] to filter buckets (wires, nets, components, …)

edit_schematic

Edit a .SchDoc (move/rotate, parameters, place component, wires, buses, net labels, power ports, …)

get_pcb_layers / get_pcb_rules / get_all_nets / get_pcb_layer_stackup

Active focused PCB queries

get_all_designators

All component designators on the PCB

get_component_pins

Pins for given designators

file_mode_capabilities

Whether offline .PcbLib/.SchLib tools are wired (extension point)

DelphiScript source

The altium-scripts/ tree is MIT-licensed code derived from coffeenmusic/altium-mcp, with additions such as ping, get_schematic_data / schematic export, and schematic_edit. See NOTICE.

File-mode (offline libraries)

Not bundled by default. See docs/file-mode.md and packages/file-ops/README.md.

Scripts

Command

Description

npm run build

Compile TypeScript to dist/

npm start

Run MCP server (stdio)

npm test

Vitest

npm run lint

tsc --noEmit

Releases and tags

This repo uses semantic version Git tags of the form vMAJOR.MINOR.PATCH (for example v0.1.0), aligned with package.json when practical. Check the tags page (or Releases) on GitHub to jump to a specific version.

Contributing

Issues and pull requests are welcome. This project is not affiliated with Altium; keep discussion technical and respectful.

Before you open a pull request

  • Use a focused branch and describe what changed, why, and how to verify (manual Altium steps if applicable).

  • Run npm run build, npm test, and npm run lint locally. CI runs the same on Node 22 (see .github/workflows/ci.yml).

  • Changes under altium-scripts/ often need a quick check in Altium Designer on Windows; state the AD major version you used when you can.

  • DelphiScript here builds on upstream work — follow attribution and licensing notes in NOTICE when editing bundled scripts.

Scope and quality

  • Prefer small, reviewable PRs. For large refactors or new subsystems, open an issue first to agree on direction.

  • New or changed MCP tools should stay consistent with src/toolDefinitions.ts, update JSON schemas in schemas/ when the bridge contract changes, and add or extend tests where behavior is verifiable in Node (Vitest).

License

By contributing, you agree your contributions are licensed under the same terms as this repository — see LICENSE (MIT).

License

MIT — see LICENSE.

Available Tools

13 tools
altium_pingPing Altium bridgeA
Read-onlyIdempotent

Purpose: Verify the DelphiScript bridge responds inside Altium.

When to use: After get_server_status looks good; before expensive PCB/schematic reads.

Parameters: None.

Returns: Bridge JSON { success, result: { protocolVersion, pong: true } } on success.

Prerequisites: Altium may be started by the bridge. AD must be installed.

Errors: Same as other live tools (AD_NOT_FOUND, TIMEOUT, lock timeout, etc.).

Inputs: no named parameters.

configure_altium_exeSave Altium X2.EXE pathA
Idempotent

Purpose: Persist the absolute path to Altium X2.EXE for bridge launches.

When to use: get_server_status shows altiumExeFound false or wrong AD version path.

Parameters: path — absolute path to X2.EXE (file must exist).

Returns: { ok: true, altiumExePath } or MCP error text if file missing.

Prerequisites: Valid X2.EXE on disk.

Notes: Writes %USERPROFILE%.altium-mcp\config.json (or equivalent). Env ALTIUM_MCP_ALTIUM_EXE overrides at runtime without persisting.

Inputs: path (required).

edit_schematicEdit schematic sheetA
Destructive

Purpose: Edit one schematic sheet (.SchDoc) via a single tool with multiple modes (action).

When to use: Move or rotate symbols, set parameters, place components, add text/net labels, wires, buses, bus entries. After editing, call get_schematic_data on the same sheet to verify.

Sheet targeting (required): Provide schematic_full_path (absolute .SchDoc, preferred) OR schematic_sheet_file_name (file name only, e.g. Sheet1.SchDoc) with project_full_path or Altium focused project.

Common parameters: action (string), schematic_full_path?, project_full_path?, schematic_sheet_file_name?

Actions:

  • set_component_transform — designator (required); optional x_mils, y_mils, rotation_deg (at least one of position/rotation must be set). Coordinates in mils; rotation in degrees (snapped to 0/90/180/270).

  • set_component_parameters — designator (required); parameter_names[] and parameter_values[] (same length; updates existing parameters or adds new ones).

  • place_component — lib_reference, designator, x_mils, y_mils, rotation_deg (optional, default 0); sch_library_path (absolute .SchLib) strongly required for a real symbol. Without sch_library_path the bridge only creates an empty schematic component shell (designator + LibReference, no library graphics—pins/body do not appear). With sch_library_path the bridge uses PlaceSchComponent from that file. All coordinates are sheet mils in the same space as get_schematic_data schematic_x/schematic_y; place inside the white drawing area (use existing objects on the sheet as reference, typically thousands of mils, not pixel-scale values).

  • add_text — text, x_mils, y_mils (free string on sheet).

  • add_net_label — net_name, x_mils, y_mils; optional rotation_deg.

  • place_net_label — alias of add_net_label (response echoes the action you sent).

  • add_wire — wire_points_csv: comma-separated mils pairs for orthogonal polyline segments, e.g. "0,0,1000,0,1000,500" creates (0,0)-(1000,0) and (1000,0)-(1000,500).

  • place_wire — alias of add_wire.

  • add_bus — same wire_points_csv format as add_wire; creates bus segments (eBus) instead of wires.

  • add_bus_entry — wire_points_csv must be exactly four numbers x1,y1,x2,y2 (mils) for one bus-entry segment (eBusEntry).

  • place_power_port — power_port_style (required): circle | arrow | bar | wave | gnd_power | power_ground | gnd_signal | signal_ground | gnd_earth | earth; x_mils, y_mils; optional net_name (defaults by style: GND for ground styles, VCC for supply styles), rotation_deg, show_net_name (default true).

  • place_gnd — same coordinates; optional power_port_style (default gnd_power in bridge), optional net_name (default GND if empty).

  • place_vcc — same coordinates; optional power_port_style (default arrow in bridge), optional net_name (default VCC if empty).

Returns: Bridge JSON result object with action, sheet, details (mode-specific). On Delphi-side failure, error text may start with ERROR: (e.g. COMPONENT_NOT_FOUND, SHEET_REQUIRED).

Prerequisites: Target .SchDoc must belong to an open project. Bridge command schematic_edit.

Notes: Does not auto-save the document unless the user saves in Altium. API behavior may vary slightly by AD major version. Wires and buses use straight segments (Location–Corner per segment). Delphi errors for buses include FACTORY_BUS_FAILED, BUS_POINTS_CSV_REQUIRED, FACTORY_BUS_ENTRY_FAILED, BUS_ENTRY_POINTS_NEED_EXACTLY_FOUR_NUMBERS, BUS_ENTRY_POINTS_CSV_REQUIRED. Power ports (ISch_PowerObject): POWER_PORT_STYLE_REQUIRED, POWER_PORT_STYLE_INVALID, FACTORY_POWER_OBJECT_FAILED, X_Y_MILS_REQUIRED.

Debugging / freezes: If the Altium Script IDE has a breakpoint set in Altium_API or schematic_edit (or Run with debugger), the script stops before writing response.json and the MCP client will see TIMEOUT. Clear all breakpoints, use Run without debugging, or press Continue/Stop Debugging in Altium. After a TIMEOUT, if no later tool runs, delete .bridge.lock in the MCP workspace folder so the next call is not blocked by the lock wait.

Inputs: action (required), text, x_mils, y_mils, +13 more.

file_mode_capabilitiesFile-mode capabilitiesA
Read-onlyIdempotent

Purpose: Report offline / file-mode features (e.g. future Rust sidecar for .PcbLib).

When to use: Check if non-live file tools exist in this build.

Parameters: None.

Returns: JSON capability flags (Node only, no Altium).

Prerequisites: None.

Inputs: no named parameters.

get_all_designatorsComponent designatorsA
Read-onlyIdempotent

Purpose: All component reference designators on the active PCB.

When to use: Quick inventory before get_component_pins.

Parameters: None.

Returns: String array of designators (parsed in Node from get_all_component_data).

Prerequisites: Active/focused PCB.

Notes: Same underlying command as full component geometry data but lighter response.

Inputs: no named parameters.

get_all_netsList PCB netsA
Read-onlyIdempotent

Purpose: Unique net names on the active PCB.

When to use: Netlist-style checks, signal naming audit.

Parameters: None.

Returns: JSON array of net name strings.

Prerequisites: Active/focused PCB.

Inputs: no named parameters.

get_component_pinsComponent pinsA
Read-onlyIdempotent

Purpose: Pin-level data for selected components on the active PCB.

When to use: After designators are known; net names per pin, etc.

Parameters: designators — string array, e.g. ["U1","R2"].

Returns: Bridge JSON with pin information per requested designator.

Prerequisites: Active/focused PCB; designators must exist on board.

Errors: Bridge may fail if designator missing or command errors.

Inputs: designators (required).

get_pcb_layersList PCB layersA
Read-onlyIdempotent

Purpose: List electrical and mechanical layer metadata for the active PCB.

When to use: Layer stack review, export layer names/ids.

Parameters: None.

Returns: Bridge-specific JSON (layer names, kinds, etc.).

Prerequisites: Correct .PcbDoc open and active (focused) in Altium.

Errors: Empty or partial data if no board focused.

Inputs: no named parameters.

get_pcb_layer_stackupPCB layer stackupA
Read-onlyIdempotent

Purpose: Physical stackup (dielectrics, thicknesses) for the active PCB.

When to use: Impedance / SI questions tied to stackup.

Parameters: None.

Returns: JSON stackup structure from the bridge.

Prerequisites: Active/focused PCB.

Inputs: no named parameters.

get_pcb_rulesList PCB design rulesA
Read-onlyIdempotent

Purpose: List PCB design rules from the active board.

When to use: DRC-related questions, clearance/copper rules review.

Parameters: None.

Returns: JSON describing rules (short descriptors per rule).

Prerequisites: Active/focused PCB in Altium.

Inputs: no named parameters.

get_schematic_dataSchematic sheet (filtered export)A
Read-onlyIdempotent

Purpose: Export schematic sheet content with optional filtering so large sheets do not flood the agent context.

When to use: BOM/placement review, wiring checks, sheet size for placement, or verify edit_schematic results. Prefer include_queries with a small subset on busy designs.

Parameters (all optional):

  • schematic_full_path: absolute path to one .SchDoc in an open project (slashes / or ). Preferred for multi-project workspaces.

  • project_full_path: absolute path to open .PrjPcb / .PrjScr. Use with schematic_sheet_file_name or alone for all SCH sheets in that project.

  • schematic_sheet_file_name: file name only (e.g. Sheet1.SchDoc). Requires focused project or project_full_path.

  • include_queries: string array selecting what to return. Omit entirely for legacy JSON (backward compatible): only { components, drawing_objects }. If present, response uses schematic_data_mode "filtered" and only the requested buckets (plus include_queries echo). Token all expands to every supported bucket. Supported tokens: sheet | components | wires | buses | net_labels | power_ports | text_labels | junctions | ports | off_sheet_connectors | sheet_symbols | directives | figures | harness | drawing_objects. harness currently returns an empty array (placeholder for future API). drawing_objects is the combined non-component list (same mix as legacy). sheet returns sheets[] with one object per matched .SchDoc (size in mils, grids, borders, template path, etc.).

Resolution order: schematic_full_path wins; else project_full_path + optional sheet file name; else focused project. Without schematic_full_path / sheet file name, all SCH documents in the chosen project are scanned (aggregated arrays / multiple sheets[] entries).

Primitive shape (per object): object_kind, object_id, bbox_*_mils, plus type-specific fields (vertices_mils for wire/bus/polyline, x1/y1/x2/y2 for line/bus entry, text for net labels / power / text labels, etc.) — same as legacy drawing_objects entries.

Prerequisites: Target project must be open in Altium. Does not require active PCB.

Errors: ERROR: NO_WORKSPACE, NO_FOCUSED_PROJECT, PROJECT_NOT_FOUND, SCHEMATIC_NOT_IN_OPEN_PROJECTS (Delphi); bridge errors otherwise.

Notes: Invalid include_queries tokens only (no matches) fall back to legacy mode. Does not flatten pins inside components or sheet entries inside sheet symbols.

Inputs: include_queries, project_full_path, schematic_full_path, schematic_sheet_file_name.

get_server_statusAltium MCP server statusA
Read-onlyIdempotent

Purpose: Inspect MCP + Altium bridge setup before other tools.

When to use: First call in a session, or after MCP/Altium install or path errors.

Parameters: None.

Returns: JSON with platform, workspaceRoot, requestPath, responsePath, scriptProjectPath, altiumExePath, altiumExeFound, scriptProjectFound, bundledScriptsDir, bridgeLastError (contents of bridge_last_error.txt if present), bridgeUserReportedError (user-pasted Altium Messages / compile text from bridge_user_reported_error.txt), diagnosticsHint, env (ALTIUM_MCP_WORKSPACE, ALTIUM_MCP_ALTIUM_EXE).

Prerequisites: None. Triggers script bundle sync into workspace/AltiumScript.

How to interpret: If altiumExeFound or scriptProjectFound is false, fix paths (configure_altium_exe or env) before live tools. For DelphiScript compile errors Altium does not send to the bridge: paste the Messages output into workspace bridge_user_reported_error.txt, then re-run get_server_status so the agent can read it. Failed bridge runs also write bridge_last_error.txt and live tools append that file into the error field when success is false.

Inputs: no named parameters.

get_workspace_projectsWorkspace projects and filesA
Read-onlyIdempotent

Purpose: List every open workspace entry (projects + logical documents).

When to use: Discover project_full_path, schematic_full_path, or confirm which .PrjPcb is focused.

Parameters: None.

Returns: JSON with projectCount, focusedProjectFullPath, focusedProjectIndex, projects[]. Each project has index, projectFullPath, projectFileName, logicalDocumentCount, focused, documents[] { kind, fullPath, fileName }.

Prerequisites: Altium running. Includes non-design entries (e.g. Free Documents, AltiumScript MCP project).

Notes: Logical documents are project members, not necessarily every editor tab.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool targets a distinct resource or action: workspace projects, server status, configuration, ping, schematic data, schematic editing, PCB layers, rules, nets, stackup, designators, pin data, and file-mode capabilities. There is no meaningful overlap or ambiguity between tool purposes.

    Naming Consistency4/5

    Read operations consistently use get_ prefixes (get_workspace_projects, get_schematic_data, get_pcb_layers, etc.), while write/configuration tools use verb-based names (edit_schematic, configure_altium_exe, altium_ping). The pattern is mostly predictable, with a minor deviation in file_mode_capabilities which is a noun phrase rather than a verb-oriented name.

    Tool Count5/5

    13 tools is well-scoped for an Altium design automation server, covering workspace discovery, bridge diagnostics, schematic read/edit, and PCB inspection. Each tool serves a clear purpose without unnecessary bloat or missing core functionality.

    Completeness4/5

    The tool surface covers schematic data retrieval and editing, plus PCB layer, rule, net, stackup, designator, and pin queries. Minor gaps exist such as lack of PCB editing or project creation, but the core inspection and schematic modification workflows are well supported.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables MCP clients like Claude Code to control a running EasyEDA Pro instance for PCB design automation, including DRC checks, project management, and script execution via a bridge server.
      33 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables MCP-compatible assistants to inspect and edit the open PCB in KiCad, including reading board info, footprints, nets, tracks, selection, and BOM data, as well as moving footprints, adding tracks and text, updating BOM fields, and saving the board.
      13
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Read-only MCP server that lets AI assistants (Claude Code, Claude Desktop, VS Code, ...) inspect Altium Designer projects — schematics, netlist, BOM and PCB — on Linux, macOS or Windows, without Altium Designer installed.
      13
      4
      AGPL 3.0