altium-mcp
Altium Model Context Protocol server and Altium API script
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/coffeenmusic/altium-mcp with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/coffeenmusic/altium-mcp'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/coffeenmusic--altium-mcp)HTML
<a href="/listings/coffeenmusic--altium-mcp"><img src="/api/listings/coffeenmusic--altium-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
The easiest way to install is to use Claude Code, point it to this repo and ask it to install it for you. Or alternatively, see below.
[Watch on YouTube](https://youtu.be/HKQMK-hluLs)
1. Make sure Claude has Python 3.10+ installed: `drop down > File > Settings > Extensions > Advanced > Python`. If not, install Python and add it to PATH. 2. Download the `altium-mcp.dxt` desktop extension file from [releases](https://github.com/coffeenmusic/altium-mcp/releases) 3. In Claude Desktop on Windows: `drop down > File > Settings > Extensions > Advanced > Install Extension...` Select the .dxt file
You shouldn't need to restart Claude and you should now see altium-mcp in the tool menu near the search bar.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 342 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # Altium MCP Server
- TLDR: Use Claude to control or ask questions about your Altium project.
- This is a Model Context Protocol (MCP) server that provides an interface to interact with Altium Designer through Python. The server allows for querying and manipulation of PCB designs programmatically.
- ## Example commands
- - Run all output jobs
- - Create a symbol for the part in the attached datasheet and use the currently open symbol as a reference example.
- - Create a schematic symbol from the attached MPM3650 switching regulator datasheet and make sure to strictly follow the symbol placement rules. (Note: Need to open a schematic library. Uses `server\symbol_placement_rules.txt` in the extension's install folder as pin placement rules. Please modify for your own preferences; an extension update replaces the file, so keep a copy.)
- - Create an op-amp symbol with a triangle body like the other op-amps in my library (symbols support line/polygon/arc/ellipse/label body graphics, not just rectangles)
- - Find me the LM358 symbol in my opamp library and open it
- - Create a multi-part symbol for a quad op-amp from the attached LM324 datasheet (creates parts A, B, C, D with shared V+/V- power pins)
- - Create a PCB footprint for the SMD part in the attached datasheet and add it to my open PcbLib
- - Duplicate my selected layout. (Will prompt user to now select destination components. Supports Component, Track, Arc, Via, Polygon, & Region)
- - Show all my inner layers. Show the top and bottom layer. Turn off solder paste.
- - Get me all parts on my design made by Molex
- - Give me the description and part number of U4
- - Place the selected parts on my pcb with best practices for a switching regulator, then verify clearances and show me a screenshot of the result
- - Auto-place my silkscreen, then fix the designators the placer left on top of parts or far from them
- - Give me a list of all IC designators in my design
- - Get me all length matching rules
- - Check my project is ready for fabrication: unsaved documents, ERC errors, and which layers my Gerber output job plots
- - Draw a schematic of an LED with a current-limiting resistor on a new sheet, using symbols from my library
- ## Videos
- - [RP2354B Symbol & Footprint w/ Claude](https://youtu.be/m8W89txJ2wY): tell Claude to build a symbol and footprint, and it handles the rest
- - [Can Opus 5.5 make a 6,545 pin symbol in Altium?](https://youtu.be/H8aqGX4gpH8): a symbol for the XCVP1902, made in Claude Code
- - [Can Opus 5.5 make difficult Altium footprints?](https://youtu.be/DOWtJsfCKPw): examples of Claude making difficult footprints
- More on the [altium-mcp YouTube channel](https://www.youtube.com/@altium-mcp), including the install walkthrough and videos for individual tools below.
- ## Installing the MCP Server
- The easiest way to install is to use Claude Code, point it to this repo and ask it to install it for you. Or alternatively, see below.
- [Watch on YouTube](https://youtu.be/HKQMK-hluLs)
- 1. Make sure Claude has Python 3.10 to 3.14 installed: `drop down > File > Settings > Extensions > Advanced > Python`. If not, install Python and add it to PATH. Python 3.15 is untested (see [Bootstrap Venv](#bootstrap-venv-recommended)).
- 2. Download the `altium-mcp.dxt` desktop extension file from [releases](https://github.com/coffeenmusic/altium-mcp/releases)
- 3. In Claude Desktop on Windows: `drop down > File > Settings > Extensions > Advanced > Install Extension...` Select the .dxt file
- You shouldn't need to restart Claude and you should now see altium-mcp in the tool menu near the search bar.
- 
- ## Creating a new .dxt (For Developers)
- ### Bootstrap Venv (Recommended)
- This approach ships a small bootstrap script (`start_server.py`) that creates a virtual environment and pip-installs dependencies on the user's machine at first launch. The .dxt is small (about 300 KB) and works on Python 3.10 to 3.14.
- **Python versions:** 3.10 to 3.13 install the hash-locked `requirements.txt`. 3.14 has no wheel for the locked pillow, so it installs the fallback list in `start_server.py` instead. With `mcp` 1.30 that list no longer caps pydantic, so it also resolves on 3.15, but 3.15 has not been tested.
- The older approach of bundling pre-compiled packages in `server/lib/` is no longer recommended — it breaks when the user's Python version doesn't match the version used to build the bundled `.pyd` files (e.g. pydantic_core compiled for 3.11 fails on 3.13).
- **How it works:**
- 1. `start_server.py` (at the repo root) looks for a ready virtual environment in `%USERPROFILE%\.altium-mcp\venvs\<key>`, where `<key>` is a hash of the pinned requirements and the Python version
- 2. If it isn't ready, it starts a **detached** builder process (`start_server.py --build`) that creates the venv and pip-installs the dependencies, then waits for it. It installs the hash-locked `requirements.txt` when the package contains it, and falls back to the short `REQUIREMENTS` list in `start_server.py` when the file is missing or the locked wheels don't fit the interpreter. Claude Desktop kills a server that has not answered within about 60 seconds, and restarts servers freely; a build that ran inside the launcher died with it. The detached builder finishes regardless, so a restarted launcher finds the venv ready or a build still in progress.
- 3. A lock file (holding the builder's PID) makes sure only one build runs at a time; other launchers wait for it. A lock whose owner has exited is taken over immediately.
- 4. It then launches `server/main.py` using the venv's Python
- 5. First launch takes ~20-30 seconds; subsequent launches are instant
- The venv, `config.json`, `build.log` and the server log `altium_mcp.log` live in `%USERPROFILE%\.altium-mcp`, not in the extension folder, because Claude Desktop replaces the extension folder on every update. The slow build therefore happens once per machine (and again only when the requirements or Python version change), and a hand-picked Altium path survives updates. AppData is deliberately avoided: Claude Desktop is an MSIX package, and writes its child processes make under AppData are redirected into `...\Packages\Claude_...\LocalCache`, so a venv built from a terminal and one built by the server would end up in different places. Set the `ALTIUM_MCP_HOME` environment variable to use a different folder. A `config.json` left beside `server/main.py` by an older version is migrated automatically on first start. The server log rotates at 1 MB (three backups) and records INFO and above; set `ALTIUM_MCP_LOG_LEVEL=DEBUG` to include every MCP protocol message.
- On a slow network the first build can exceed the client's 60-second startup timeout. The build carries on in the background, so restarting the extension once it has finished is enough; `build.log` shows progress.
- **Build steps:**
- 1. Make sure `start_server.py` exists at the repo root
- 2. Make sure `server/main.py` does NOT have the old `site.addsitedir` hack at the top
- 3. Update `manifest.json`: set `entry_point` to `start_server.py`, remove any `env`/`PYTHONPATH` fields, and use `manifest_version: "0.3"`
- 4. Package the DXT — either use `dxt pack` or manually zip and rename:
- ```powershell
- Compress-Archive -Path manifest.json, start_server.py, pyproject.toml, requirements.txt, server -DestinationPath altium-mcp.zip
- Rename-Item altium-mcp.zip altium-mcp.dxt
- ```
- Build from a clean checkout. Release packages leave out `server/tests/`, `__pycache__` folders, `*.pyc` and log files.
- **Do NOT include `server/lib/` or `server/.venv/` in the .dxt.** The whole point is that these are created on the user's machine.
- **`start_server.py`:** use the file at the repo root as is. It is no longer reproduced here, so the two cannot drift apart.
- **`manifest.json` server section:**
- ```json
- "server": {
- "type": "python",
- "entry_point": "start_server.py",
- "mcp_config": {
- "command": "python",
- "args": ["${__dirname}/start_server.py"]
- }
- }
- ```
- ### Pitfalls
- These are hard-won lessons from debugging DXT builds. Violating any of these will produce errors that are difficult to diagnose.
- 1. **Do NOT use `os.execv()` in `start_server.py`.** The DXT installs to a path containing spaces (`Claude Extensions`). On Windows, `os.execv` splits the path at the space and fails. Use `sys.exit(subprocess.call([...]))` instead.
- 2. **Pin `mcp` to an exact version (now `==1.30.0`) and upgrade it deliberately.** An open range pulls in whatever is newest, and FastMCP has changed under the server before: 1.x dropped the `description` kwarg of `FastMCP.__init__()`, and in later 1.x releases a tool declared `-> str` sends its result a second time as `structuredContent` unless it is registered with `structured_output=False` (what `_tool()` in `main.py` does). mcp 2.x is not supported.
- 3. **Do NOT use `manifest_version: "0.4"` with `"type": "uv"`.** Claude Desktop does not support it yet. You will get `Invalid manifest: server: Required`. Use `"type": "python"` with `manifest_version: "0.3"`.
- 4. **After removing the `site.addsitedir` hack from `main.py`, fix the `pathlib.Path` reference.** The hack included `import pathlib` at the top of the file. The logging setup later uses `pathlib.Path(...)` which will throw `NameError` once that import is gone. Change it to `Path(...)` — the `from pathlib import Path` import already exists in the file, just make sure it comes before the logging setup.
- 5. **Do NOT bundle `server/lib/` in the DXT.** That was the old approach and defeats the purpose of the venv bootstrap.
- ### Legacy: Bundled server/lib (Not Recommended)
- This approach bundles all dependencies in `server/lib/` and sets `PYTHONPATH` to point to it. It produces a much larger .dxt (~17 MB) and **only works if the user's Python version matches the version used to compile the bundled packages**.
- 1. Populate packages: `python -m pip install --no-cache-dir --target server/lib -r requirements.txt`
- 2. Set the manifest `entry_point` to `server/main.py` and add `"env": {"PYTHONPATH": "${__dirname}/server/lib"}` to `mcp_config`
- 3. Package: `npm install -g @anthropic-ai/dxt && dxt pack`
- ### DXT Resources
- - [Desktop Extensions](https://www.anthropic.com/engineering/desktop-extensions)
- - [Desktop Extensions Github](https://github.com/anthropics/dxt)
- - [Getting Started with DXT](https://support.anthropic.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)
- - [Python DXT Example Code](https://github.com/anthropics/dxt/tree/main/examples/file-manager-python)
- - [DXT Manifest](https://github.com/anthropics/dxt/blob/main/MANIFEST.md)
- ## Configuration
- The server finds your Altium Designer installation by itself, and uses the newest build when several are installed. It looks first at the builds Altium's installers record in the registry (`HKLM\SOFTWARE\Altium\Builds`), wherever Altium was installed, then at a running Altium, and last in `C:\Program Files\Altium`. If it finds none, it asks you to select the Altium executable (X2.EXE) the first time a tool runs; it never asks while the server is starting. The choice is kept in `config.json` in the data folder (see above). Altium's DelphiScript scripting is used to create an API between the mcp server and Altium.
- ## Available Tools
- The server provides several tools to interact with Altium Designer:
- ### Output Jobs
- - `get_output_job_containers`: Reads all available output containers from the `.OutJob` at `outjob_path` (a full path, optional) or, without one, from the first OutJob open in a project
- - `run_output_jobs`: Pass a list of output job container names to run any number of them, from the `.OutJob` at `outjob_path` or the first open one. The OutJob's project must be open in Altium. PDF containers report `output_verified` once the PDF is written. If the PDF already exists and the container prompts before overwriting, Altium asks in a dialog and the run waits for the answer.
- - `get_outjob_settings`: Read any `.OutJob` file from disk (no Altium needed, the OutJob does not have to be open) and return its containers (output paths, file name expression, add-to-project) and outputs (connected containers, variant, document) with decoded settings: Gerber units/format/origin and the plotted and "add to all plots" layers decoded from Altium layer IDs, NC Drill, IPC-D-356 test points, pick and place, print layers and BOM sections. Use it to audit fabrication settings before generating. Reads the saved file, so unsaved changes in Altium are not visible.
- - `create_outjob`, `edit_outjob`: Create an OutJob (from one of your OutJobs as a template, or empty) and add it to a project; change its containers (add a PDF or generated-files container with its folder and file name, rename, remove) and outputs (copy an output from another OutJob into chosen containers, remove, rename, enable, move between containers, change one setting of its configuration). Edits keep everything else exactly as Altium wrote it, and nothing is written when any operation fails; an OutJob open in Altium is closed first and reopened after, and Altium is not started for an edit. A new container copies the settings of one of its type but not its folder or file name. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #75](https://github.com/coffeenmusic/altium-mcp/pull/75)).
- ### Project & Validation
- - `list_open_documents`: List the documents open in Altium with their path, kind, whether they have unsaved changes and which one is in front.
- - `reload_document`: Close an open document and open it again from disk, e.g. after the file was replaced outside Altium (which otherwise saves its own copy over it). A document with unsaved changes is refused unless `discard_changes`. Returns the file's size and modification time as loaded.
- - `get_project_info`: Focused project's parameters, documents with their state (`closed` / `open` / `modified` = unsaved changes in memory), schematic sheet count and variants with their variations (e.g. Not Fitted parts). Read-only; use it to confirm nothing is unsaved before generating outputs.
- - `preview_eco`: What Design > Update PCB would change, as data, without running it: components to add, remove or change (designator, footprint, comment), nets to add, remove or rename, pins changing net, component and net classes, and rooms the update would add or remove. Components match by unique id and nets by their pins, as the comparator does. The project's saved options are followed: kinds the comparator ignores or the ECO does not generate, and classes and rooms Class Generation does not make, are left out and counted in `skipped_by_project_options`. Board parts with no schematic link are listed apart (`board_only_components`), as the ECO leaves them alone. Also explains duplicate component class names (Altium's "Class already exists" warning from a sheet symbol that lists several files). Not compared: net class members, component parameters, differential pairs, rules from parameter sets, and room scope and members, so an empty result means no differences of the kinds compared. Read-only: compiles in memory and reads the board without bringing it to the front (a board it had to open is closed again; one already open stays open). Contributed by [SiboVG](https://github.com/SiboVG) ([PR #84](https://github.com/coffeenmusic/altium-mcp/pull/84)).
- - `compare_netlist`: Compile a project and compare its netlist with a saved snapshot: the safety net for editing sheets in place. Lists nets that gained or lost pins, pins moved between nets, nets added, removed or renamed (an auto-named net whose pins stay together is a rename; nets are matched by name, then greedily by most shared pins) and nets left with a single pin. By default each call compares with the previous one and saves itself (`against` / `save_as` name a fixed baseline). Snapshots are kept per project by its full path, so a copy of a project in another folder keeps its own; the 20 most recently saved per project are kept and older ones removed (listed in `pruned`). A malformed snapshot gives an error, not a comparison. Read-only: compiles in memory. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #93](https://github.com/coffeenmusic/altium-mcp/pull/93)).
- - `get_project_components`: The components of the compiled project with their schematic Comment, footprint, library reference and sheet (optionally all parameters, or only the ones you name). Filter by designator (wildcards such as `R*`) or sheet; a large project comes in pages, and `next_offset` says where to go on. Use it for BOM work: the instance Comment is where generic passives keep their value, which PCB-side tools and ActiveBOM may not show. Takes an optional `project_path`, as `get_erc_violations` does.
- - `get_erc_violations`: Compile a project in memory (nothing is saved) and list compiler/ERC violations with their level (fatal / error / warning). Give `project_path` (a `.PrjPcb`, opened if needed) to compile exactly that project; without it the focused project is compiled, and Free Documents is refused. The result names the project it compiled and lists the sheets compiled from unsaved changes in Altium (`unsaved_in_altium`) and those missing on disk. Violations are read from the project object - the per-document `DM_ViolationCount` does not exist in recent Altium versions. `project_path` contributed by [SiboVG](https://github.com/SiboVG) ([PR #80](https://github.com/coffeenmusic/altium-mcp/pull/80)).
- - `get_board_summary`: Fabrication-oriented summary of the focused PCB in mm: board outline (bounding box, size, vertices) and origin, dimension objects, vias by hole size, components per side, primitive counts per layer (free vs. inside components, e.g. to see which mechanical layers hold the assembly outlines) and the free texts on both overlays.
- - `get_component_primitives`: Every primitive of the given components with its layer (pads with size and solder/paste mask expansion, arcs, tracks, texts). Catches footprints that were flipped to the bottom side but kept part of their copper or mask opening on the top (e.g. fiducials).
- ### Component Information
- - `get_all_designators`: Get a list of all component designators in the current board
- - `get_all_component_property_names`: Get a list of all available component property names
- - `get_component_property_values`: Get the values of a specific property for all components
- - `get_component_data`: Get detailed data for specific components by designator
- - `get_component_pins`: Get pin information for specified components
- ### Schematic/Symbol
- - `get_schematic_data`: Get schematic data for specified components
- - `create_schematic_symbol` ([YouTube](https://youtu.be/MMP7ZfmbCMI)): Passes pin list with pin type & coordinates to Altium script. Supports multi-part symbols (e.g. quad op-amps) via a `part_count` parameter and an `owner_part_id` field on each pin (use 0 for shared power/GND pins), active-low pin name overbars by placing a backslash after each overbarred character (e.g. `R\E\S\E\T\` renders as `RESET` with overbar), per-pin length and name/designator visibility, and an optional `graphics` list (lines, polylines, polygons, rectangles, arcs, ellipses, labels) for non-rectangular bodies like op-amp triangles and diode glyphs. When creating a symbol, the agent is instructed to first look up a similar symbol in an available library as a style reference (skipped gracefully if no library is available).
- - `get_symbol_primitives`: Inventory a .SchLib (every symbol with per-type primitive counts) or dump one symbol's complete geometry (all graphics + pin details, in mils; `symbol_name="*"` dumps every symbol). Used to gap-analyze a library, to give the agent a reference example when drawing a new symbol, and to verify recreations. The symbol creator round-trips a complete production library set exactly - 514/514 symbols across IC, connector, misc, and passives libraries (dump -> recreate -> dump -> diff, zero differences). Footprint/model links (implementations) are metadata outside the graphics round-trip. Each dumped symbol also reports its Comment (`text`, `visible`) and its parameters (`name`, `value`, `visible`, location in mils as Altium holds it, `justification`, `autoposition`, `font` name and size), and each pin its `description`, its four IEEE symbols (`symbol_inside`, `symbol_inside_edge`, `symbol_outside_edge`, `symbol_outside`) and its parameters (`name`, `value`), so the agent can check symbol properties after setting them.
- - `create_symbols_batch`: Create or edit many symbols in one script run from a plain-text spec file (bulk imports/migrations) - far faster and more robust than one create call per symbol. Besides `SYMBOL`, `PIN` and `GRAPHIC` records it takes:
- - `EDITSYMBOL|<name>`: edit an existing symbol. A symbol that is not in the library is reported under `failed`, never created.
- - `COMMENT|<text>[|<visible 1/0>]`: set the Comment. It is hidden unless the visible field is 1. The library editor keeps its own copy of the Comment of the symbol on screen and writes that copy back when it shows another symbol, so for that symbol the tool sets both.
- - `DESCRIPTION|<text>`: set the Description.
- - `SYMPARAM|<name>|<value>|<visible 1/0>[|x|y[|justification[|font]]]`: add or replace a symbol parameter. By default, visible parameters without a location go below the body's bottom-left corner, left-aligned, 100 mil apart in record order. The optional justification is `bottom_left`, `bottom_center`, `bottom_right`, `center_left`, `center`, `center_right`, `top_left`, `top_center` or `top_right`. The optional font is `<font name>:<size>`, for example `Arial:10`; it is looked up by name with `FontManager.GetFontID`, which adds it to the document when missing, because font IDs differ between documents. Leave a field empty to skip it and still give a later one; omitted fields keep the parameter's own. A parameter the tool positions gets Autoposition off, so Altium does not move it afterwards.
- - `PINPARAM|<pin number>|<name>|<value>`: add or replace a hidden parameter on every pin with that number (every part of a multi-part symbol).
- - `PINDESC|<pin number>|<text>`: set the Description of every pin with that number.
- - `PINSYMBOL|<pin number>|<edge>|<symbol>`: set an IEEE symbol of every pin with that number. The edge is `inside`, `inside_edge`, `outside_edge` or `outside`. The symbol is a TIeeeSymbol name without the leading `e`, in any case: `none`, `dot`, `clock`, `activelowinput`, `schmitt` and so on (the full list is in the altium-script skill, SCH_API_Reference.md, under TIeeeSymbol).
- - `PINFUNC|<pin number>|<F1>/<F2>/...` (optional): replace the Functions list (Properties panel > Pin > Functions) of every pin with that number, in the order given, for multi-function pins such as GPIOs. Nothing sets functions unless the spec has this record. A script cannot clear the list, so an empty one is listed under `problems`, and so is a stored list that differs, as when Altium merges a repeated name. `get_symbol_primitives` returns a pin's `functions` when it has any.
- These records work after `SYMBOL` and `EDITSYMBOL` alike. An unknown pin number, edge, symbol or justification is listed under `problems`; the rest of the batch still runs.
- The result lists `created`, `edited`, `failed` and `problems`. Created and edited symbols leave the library modified and unsaved, so the user reviews them and saves; the tool never saves a library. Objects a script adds through PreProcess/PostProcess do not reliably set Altium's modified flag (in a PCB library they never do), so the symbol and footprint tools set it themselves. A `LIBRARY|<path>` line focuses that library if it is already open (it never reloads it, which would discard unsaved symbols) and opens it otherwise. If that library cannot be focused, the batch stops before changing anything. The library editor draws the symbol it shows from a picture made when that symbol was shown, so new parameters on it would not appear: a batch that edited symbols therefore ends by showing another symbol and then that one again. A library with a single symbol has nothing to switch to; `problems` then says the new parameters appear once the library is reopened.
- - `build_schematic`: Build a wired schematic on a new sheet from a circuit description: parts from a `.SchLib` (full path; `.IntLib` is not supported), wires, junctions, net labels, power ports and notes, in mils (fractions are kept, so metric positions are exact). Returns every placed pin's true connection point, so a second call can route wires from measured coordinates, and lists any part it could not place. The new sheet is kept out of your project.
- - `check_schematic`: Check saved sheets for drafting problems: two-pin parts tapping their net at the pin, net labels away from their wire's free end or hanging off it, text touching wires, pins or other text (with a clear layout suggested), dangling wires, wires slightly out of level, parts whose pins sit a few microns off the grid, and sheet symbol layout. Takes a `.SchDoc`, a `.PrjPcb` or a folder and reads the saved files, so it needs no running Altium. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #64](https://github.com/coffeenmusic/altium-mcp/pull/64), pins off the grid [PR #73](https://github.com/coffeenmusic/altium-mcp/pull/73)).
- - `check_hierarchy`: Check that a project's sheets connect: every sheet entry against the ports of its child sheet (with rename suggestions for pairs that belong together under different names), harness types of entries and ports, one harness type defined differently on two sheets, signal harnesses whose type nobody gives (located, unlike the ERC's "Missing harness type"), and `.Harness` files out of step with their sheet. Reads the saved files, so it needs no running Altium.
- - `edit_schematic`: Change an existing sheet: move, rotate, mirror, delete or place parts, set parameters, move designator and parameter text, add wires, net labels, power ports, junctions and no-ERC markers, and delete objects at a point. Coordinates are in mil or mm, so `check_schematic`'s suggestions apply directly. The whole edit is one undo step in Altium, and the sheet is saved only when asked. `place_component` also places a part from a database library (Excel tables) by `dblib` and `part_number`: the row gives the symbol, footprints, description and parameters (following the field map's visibility and Add To Design settings), and the part is linked to the DbLib as when Altium places it. It also edits sheet symbols (move, resize, colours, name and file name text) and their entries (side, distance, I/O type, style, name), moves a wire vertex together with the wires, junctions, net labels, power ports and port ends on it, and moves a net label, optionally onto the nearest wire end, keeping its font and colour. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #70](https://github.com/coffeenmusic/altium-mcp/pull/70), DbLib parts [PR #91](https://github.com/coffeenmusic/altium-mcp/pull/91), sheet symbols, wire vertices and label moves [PR #92](https://github.com/coffeenmusic/altium-mcp/pull/92)).
- - `get_schematic_pins`: The pins of a sheet's parts, live from Altium: connection point, number, name, electrical type. `edit_schematic` also takes pin references ("U20.VCC", "U20.3", "U1A.3" for part A of a multi-part part) wherever it takes a point, and `add_port` places a port with a fixed width (auto size off). Pins are read before the edit runs, so a part moved or placed in the same call is referred to in a second call. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #78](https://github.com/coffeenmusic/altium-mcp/pull/78)).
- - `render_sheet`: A picture of a schematic sheet or part of it (wires, buses, junctions, component bodies with pin names and numbers, net labels, power ports, ports, sheet symbols, texts), read from the .SchDoc file, so the sheet need not be open. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #87](https://github.com/coffeenmusic/altium-mcp/pull/87)).
- - `get_symbol_placement_rules`: Create symbol's helper tool that reads `server\symbol_placement_rules.txt` in the extension's install folder to get pin placement rules for symbol creation. The file ships empty, so the tool returns neutral guidance (follow a comparable symbol in the user's library, keep pins on a 100 mil grid); put your own rules in it.
- - `get_library_symbol_reference`: Create symbol's helper tool to use an open library symbol as an example to create the symbol
- - `search_library_symbol`: Search for a symbol by name in a schematic library (.SchLib) and navigate to it. Supports partial name matching. Will open the library file in Altium if a path is provided, or show a file picker if not.
- Library paths (`library_path`, `LIBRARY|`, `FPLIB|`) may contain commas and may be spelled in a different case or with forward slashes; `LIBRARY|` and `FPLIB|` paths may also use short (8.3) folder names. An open library is matched to its path after normalizing case and separators, so the tools never open a second copy of it.
- 
- ### Layout Operations
- - `get_all_nets`: Returns a list of unique nets from the pcb
- - `create_net_class` ([YouTube](https://youtu.be/89booqRbnzQ)): Create a net class from a list of nets
- - `get_pcb_layers`: Get detailed layer information including electrical, mechanical, layer pairs, etc.
- - `get_pcb_layer_stackup`: Gets stackup info like dielectric, layer thickness, etc.
- - `set_pcb_layer_visibility` ([YouTube](https://youtu.be/XaWs5A6-h30)): Turn on or off any group of layers. For example turn on inner layers. Turn off silk. Names are matched as Altium spells them anywhere ("Multi-Layer", "Top Solder", "Mid Layer 1" for a renamed inner layer), and "Top Silk" or "Top Silkscreen" finds "Top Overlay"; an unknown name changes nothing and the reply lists the board's layers. Every reply has `previous_state`, which `restore_state` puts back.
- - `get_pcb_rules`: Gets the rule descriptions for all pcb rules in layout.
- - `run_drc`: Run Altium's design rule check on a board and list the violations, each with its rule, description, position, the objects involved and, where Altium gives them, the measured and allowed values in mils; plus the per-rule counts from Altium's report. Filter the list by rule name or kind (`rules`, whole names: "Clearance" is the electrical clearance rules only), by net or by area. The Design Rule Checker dialog flashes on screen while the tool presses Run; `ran` says whether the check really ran. Takes an optional `board_path`. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #66](https://github.com/coffeenmusic/altium-mcp/pull/66), filters and values [PR #77](https://github.com/coffeenmusic/altium-mcp/pull/77)).
- - `check_objects_drc`: Run the board's own design rules on chosen objects only (refs from `objects_in_area`, and/or every copper object in a box), without a batch DRC or its dialog: each object's width or hole-size rule, and the clearance, short-circuit and hole-to-hole rules against the copper near it, pour copper included (hits on pour copper, which is as last poured, are listed apart as `pour_violations`). Overlay, mask and mechanical objects are not checked. The rule is the one the DRC would pick and Altium's own check decides; `margin` sets how far neighbours are looked for; says so when nothing could be checked. Takes an optional `board_path`. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #94](https://github.com/coffeenmusic/altium-mcp/pull/94)).
- - `create_pcb_rule`: Add a design rule: clearance, width, hole size, routing via, solder or paste mask expansion, or polygon connect, with values in mils and Altium query scopes such as `InNet('GND')`. A rule added by script becomes priority 1 of its kind, so give it a narrow scope; the result warns when a rule scoped to everything now overrides others. Takes an optional `board_path`. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #67](https://github.com/coffeenmusic/altium-mcp/pull/67)).
- - `get_selected_components_coordinates`: Get position, rotation, layer, and footprint information for currently selected components
- - `move_components`: Move specified components by X and Y offsets
- - `set_component_position`: Set one component's absolute position and rotation
- - `place_components`: Batch absolute placement - place any number of components (x, y, rotation, top/bottom layer, locked, and optionally the designator and comment text exactly as `get_layout` reports it) in a single transaction / one undo step, on the board named by `board_path`. The workhorse for AI-driven placement.
- - `check_placement`: Verify a placement - finds overlaps and clearance violations against every other component on the board using true primitive-to-primitive distances (designator text excluded). Run after placing; a screenshot is not verification.
- - `check_orientation`: Advisory check for 2-pad passives whose rotation could be improved (e.g. a decoupling cap with its GND pad facing away from the IC). Geometry only - review suggestions with judgement; parts like pull-ups don't care.
- - `get_net_connections`: For the nets touching a set of components, list every pad on each net board-wide with per-net airline (MST) lengths - the data behind connectivity-driven placement (shorten critical nets, see off-cluster loads and filter banks).
- - `check_routing`: Check the routed copper for segments that are not 0, 45 or 90 degrees and for right-angle and acute corners, with the net, layer and position of each. Run after editing tracks or vias; a screenshot does not show a stub 2 degrees off 45. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #60](https://github.com/coffeenmusic/altium-mcp/pull/60)).
- - `route_track`: Add a track through waypoints with every segment exactly 0, 45 or 90 degrees, optionally chamfering square corners; `dry_run` only returns the segments. It adds tracks only: no vias and no DRC. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #60](https://github.com/coffeenmusic/altium-mcp/pull/60)).
- - `route_path`: Route a net from a pad, via or point through waypoints, every segment 0, 45 or 90 degrees, changing layer with a via where a waypoint names another layer. Width and via size default to the net's width and routing via style rules. Every layer is checked against the board before anything is added; a surface-mount pad reached on another layer (a via in the pad) or a pad of another net is refused unless allowed. The new copper is one undo step and is then checked like `check_objects_drc`; `undo_on_violation` takes it off again within that step, and `dry_run` only plans. Use it when you choose the path (inner layers, blind vias, a set of waypoints) and want the result checked; use `route_connections` to have a group's unrouted connections found and routed for you. Takes an optional `board_path`. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #95](https://github.com/coffeenmusic/altium-mcp/pull/95)).
- - `place_vias`: Add vias at positions in mils from the board origin, with a default size, net and layer span that each via can override (blind and buried vias too). Every net and layer is checked against the board first, by Altium's layer name or the stack's own ("Inner 1"), so a bad entry adds nothing, and all the vias are one undo step. Takes an optional `board_path`. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #68](https://github.com/coffeenmusic/altium-mcp/pull/68)).
- - `place_polygon_pour`: Add a polygon pour from an outline of corners in mils on a signal layer, solid or hatched, with an optional net, and pour it. Takes an optional `board_path`. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #69](https://github.com/coffeenmusic/altium-mcp/pull/69)).
- - `place_cutout`: Add a polygon pour cutout on one signal layer or all of them, or a board cutout, and repour the polygons it overlaps. Takes an optional `board_path`. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #69](https://github.com/coffeenmusic/altium-mcp/pull/69)).
- - `delete_pcb_objects`, `modify_pcb_objects`: Rip up copper, or change its width, via size, net or layer: tracks, arcs, vias, polygon pours, copper regions, fills and pour cutouts picked by kind, net, layer and area, or a group's copper by `designators` (exactly what `get_layout` lists for the group). Only copper is touched - never pads, component primitives, keepouts or objects on other layers - and locked objects are left alone and listed unless `include_locked`. A filter must narrow the match. A via whose hole would not fit its diameter is left as it is. `dry_run` lists the matches; each edit is one undo step. Takes an optional `board_path`. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #74](https://github.com/coffeenmusic/altium-mcp/pull/74)).
- - `repour_polygons`, `get_pour_report`: Repour every polygon pour on a board, or those picked by name, net, layer or area, in pour order (where pours of different nets overlap, the order decides which gets the copper), as one undo step; and report what each pour poured (pieces, islands, slivers, no net, no copper). Shelved polygons stay shelved unless `include_shelved` is set. Takes an optional `board_path`. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #71](https://github.com/coffeenmusic/altium-mcp/pull/71)).
- - `get_layout`: Read the layout of a group of components or of an area: each component's placement, lock and designator and comment text, and the copper around them - tracks, arcs, vias, fills, copper regions, pour cutouts and polygon pours with their full outline (arc edges included) and pour settings. For a group it lists the copper wholly inside its extent plus the copper of its own nets (nets with no pad on another part) wherever it runs. The result is exactly what `place_components` and `place_copper` take.
- - `place_copper`: Add copper in one undo step: tracks and arcs at any angle, vias, fills, copper regions, pour cutouts and polygon pours (arc edges, island and neck removal, pour order, pour over same net). Every net and layer is checked first, so a bad entry adds nothing; pours go in last and pour around the copper added with them. A `transform` (shift, rotate, mirror) and `rename_nets` place a layout read with `get_layout` somewhere else, e.g. to repeat a channel.
- - `fanout_pads`: Fan out pads - a short track from each pad to a via beside it, e.g. to take an IC's ground and power pads down to their planes. Each via goes outward from the component first, as close as the clearance allows; a pad big enough to hold the via (an exposed thermal pad) gets it in the middle. Widths come from the board's width rules (no wider than the pad), the gap from its clearance rules. Pads that already have copper on them are left alone.
- - `route_connections`: Route a group's unrouted connections automatically with a maze router: every segment 0, 45 or 90 degrees, keeping the clearance from other nets' copper on the layers allowed, and changing layer through a via where needed. Each net gets the preferred width of its width rule (its minimum where that finds no path) and the gap of its clearance rule. Wider nets go first, then shortest first; when a connection is walled in by earlier routes, the whole set is routed again with the failures first. Pours are not obstacles (repour afterwards). Everything goes in with one undo step, and the reply lists the routed and failed connections and what is still unrouted. Together with `delete_pcb_objects` (rip up a group's copper) this is the loop for routing a group from scratch: place, fan out, route, check, rip up and try again.
- Tested on groups of the 6-layer board below, placed and with the board's planes in: eleven of twelve groups (5 to 50 parts) routed completely, in 5 to 90 seconds each, with no clearance, short-circuit or width violations (several needed both outer layers, one also Mid Layer 2); the twelfth, the densest, kept 3 of its 63 connections unrouted, reported as failed.
- - `get_unrouted_connections`: The connections still to be routed (the ratsnest) for some components, some nets or the whole board, naming the pad at each end and saying whether both ends lie in the group's area. No DRC run and no 500-violation limit. Altium does not update the ratsnest after copper a script adds, so the nets are analyzed first.
- Tested by rebuilding a 6-layer board (390 parts, 2,122 tracks, 114 arcs, 463 vias, 123 pours) from a copy with its copper removed and its parts scattered: each of its 48 component groups was placed and routed in four calls (`get_layout` on the original, `place_components`, `place_copper`, `get_unrouted_connections`), about 7 minutes for all of them, and then the routing between groups. The result matched the original: every part, text, track, arc, via, cutout and pour, the same DRC result and no unrouted connections.
- - `query_objects`, `which_rule`: Find PCB objects with Altium's own query language (as the PCB Filter panel runs it), returning kind, name, net, layer (generic, plus `layer_name`, the board's own name for it) and bounds; generic layer names in OnLayer() are translated to the board's. The engine has no X or Y, so `area` ([x1, y1, x2, y2] from the board origin, in `unit`: mil or mm) keeps the objects touching a box. Sizes are given with a unit and converted to the unit the engine reads (quoted text is sent as written), and a bad expression comes back as Altium's error instead of a dialog. The user's selection is selected again afterwards, except objects of kinds the PCB Selection Filter leaves out (a script cannot select those); a filter applied in the PCB Filter panel is cleared. `which_rule` gives the design rule the DRC applies to one object (width, hole size, routing via, mask expansion, plane connect) or between two (clearance, short circuit, hole to hole, silk, component clearance, polygon connect), with the distance and whether they pass it by Altium's own check (Rule.ActualCheck); `area_a` and `area_b` pick each object by position. Takes an optional `board_path`. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #76](https://github.com/coffeenmusic/altium-mcp/pull/76), [PR #88](https://github.com/coffeenmusic/altium-mcp/pull/88)).
- - `objects_in_area`: The board objects in a box (tracks, arcs, vias, pads, fills, regions, polygons, texts, components), filtered by layer, kind and net, with board-relative coordinates in mils or mm and a `ref` for each. Through vias and Multi Layer pads count as on every copper layer, a blind via on the layers it spans. Regions, tracks and polygon pours are matched by shape, so a board-sized pour is listed only where its copper reaches the box. `get_layout` reads a group's copper to edit and place again instead. `limit` counts after the filters, and `truncated` says when the list was cut. Takes an optional `board_path`. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #86](https://github.com/coffeenmusic/altium-mcp/pull/86)).
- - `clearance`: The edge-to-edge gap between two objects (refs from `objects_in_area`, or pads as `U1-3`), with the clearance rule that applies and whether it is met. Takes an optional `board_path`. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #86](https://github.com/coffeenmusic/altium-mcp/pull/86)).
- - `drag_copper`: Move a via or a track segment and keep it connected: track ends that meet it stretch along, and a via at a moved track end moves with its tracks on the other layers. Refused when a pad, an arc or copper of the same net joined partway along a moving track (a T-junction) would be left behind, or locked copper would move; `dry_run` shows what would move. Takes an optional `board_path`. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #86](https://github.com/coffeenmusic/altium-mcp/pull/86)).
- - `render_pcb`: A picture of a board area (default the whole board): copper with pours, vias, pads, overlay and the board outline, in Altium's layer colours. Drawn from the board's objects, not captured from the window, so nothing in Altium moves or comes to the front; layers and dpi are chosen per call. Takes an optional `board_path`. Contributed by [SiboVG](https://github.com/SiboVG) ([PR #87](https://github.com/coffeenmusic/altium-mcp/pull/87)).
- - `layout_duplicator` ([YouTube](https://youtu.be/HD-A_8iVV70)): Starts layout duplication assuming you have already selected the source components on the PCB.
- - `layout_duplicator_apply`: Action #2 of `layout_duplicator`. Agent will use part info automatically to predict the match between source and destination components, then will send those matches to the place script.
- The cool thing about layout duplication this way as opposed to with Altium's built in layout replication, is that the exact components don't have to match because the LLM can look through the descriptions and understand which components match and which don't have a match. That's something that can't really be hard coded.
- 
- ### Silkscreen
- Bulk placement with the Silkscreen Auto Placer script, then an agent cleans up what it leaves. The loop is: auto-place, find what needs work, look at it, pick a spot, apply, and get Altium's verdict.
- - `auto_place_silkscreen`: Run the [Silkscreen Auto Placer](https://github.com/coffeenmusic/Silkscreen_Auto_Placer) headless inside Altium (`server/AltiumScript/silk_autoplacer.pas`, a port of the GUI script): autopositions on an offset grid with shrinking text, a retry pass and a 2nd-pass wiggle search, avoiding pads, bodies, silk and optionally vias. Options default to the settings last saved by the script's GUI (`AutoPlaceSilkscreen.ini`); any argument overrides them. Failures are centred on their part (or hidden/restored). One undo step. Differences from the GUI script: "try altered rotation" on the bottom layer flips 0/270 (the script turned mirrored text to 90/180, upside down); labels keep the Board Outline Clearance rule's distance from the board edge (the script only kept them on the board); and each placed designator's geometry is rebuilt at the end (see below). Save the board first: a run touches every designator, and Altium crashed once during one (not reproduced).
- - `check_silkscreen`: What needs work. Each designator is tested with Altium's own Silk To Silk, Silk To Solder Mask and Board Outline Clearance rules (`Rule.ActualCheck`, the same test a batch DRC runs), plus quality problems DRC does not flag: text far from its part (noting when it is still in line with it, as in a label block), reading as another same-type part's label, over a part body or left on top of its own part, over open vias, off the board, or upside down. Lists hidden designators too. Optional whole-board view.
- - `view_silkscreen`: Look at an area - designators or a mil region - rendered cleanly (mask openings, silk, part names, designator boxes) with a grid labelled in board coordinates, so a free spot can be read straight off the image. Independent of Altium's window and zoom.
- - `get_designator_options`: Ranked legal spots for designators, drawn as numbered boxes, each clear of silk, mask openings, open vias, the board edge and every other designator, readable, and nearer its own part than any same-type part (or level with its own part when a nearer part is not). When there is none, says what blocks it. Can include smaller-text options (`min_height_mils`). Ask for a designator together with its neighbours: the designators asked about are not obstacles to each other, so their labels can move to make room.
- - `get_label_block_options`: For parts in a row whose designators do not fit next to them: their designators in a row too, in the same order, where there is room, even some way off. Give one designator to use its whole row (parts side by side along x or y, similar size, gaps up to 50 mil; mounting holes, fiducials and hidden test points get no label) or list the parts; a single part works as a block of one. Each option is a block (labels across the row, in line with each part when the pitch allows or side by side; or end to end along it) and, unless it sits right against the row, a link: a silk leader line with an arrowhead pointing at the parts, or matching index markers - a capital letter in a circle, then square, then triangle - next to the block and next to the parts. Drawn per option.
- - `place_label_block`: Apply an option: the labels move (shown, at the block's text size), the link is drawn on the overlay as free tracks, arcs and text, and both are checked with Altium's silk rules. Replaces an earlier block of the same parts. Blocks are recorded per board (`C:\Users\Public\altium_mcp\silk_label_blocks.json`, never next to the board), so `check_silkscreen` knows a block's labels are linked to their parts and reports a block whose labels or link have been disturbed. `remove_label_block` deletes a block's link.
- - `remove_label_block`: Remove the label block of some parts: its link graphics (leader or index markers) are deleted, and the designators stay where they are, ready to be placed again.
- Designators are not hidden to get rid of problems: only mounting holes and fiducials go without one. A designator with no room goes in a label block.
- - `set_designator_positions`: Place designators by coordinates (text-box centre) or relative to their part (`side` = above/below/left/right/inside, `gap`, `offset`), with optional rotation, height, stroke width and visibility. `dry_run` checks a set of neighbours together without touching the board; otherwise all moves are one undo step and each moved designator comes back with Altium's DRC verdict. Moves are tied to the board they were computed for: if another PCB has been focused since, Altium refuses them and nothing moves (`check_silkscreen` reports which board it read).
- Typical run on a dense two-sided board (845 parts, 804 visible designators): the auto placer placed 725 in about 7 minutes. Many of its labels still touched each other, because the script tolerates a 4 mil designator overlap, or sat far from their part. Agent rounds of `check_silkscreen` → `get_designator_options` → `set_designator_positions` (dry run, then apply), allowing 25 mil text, took the board from 637 silk DRC violations to 367. The rest are designators with no legal spot in the densest passive fields; those go in label blocks.
- The geometry model lives in `server/silkscreen.py` and label blocks in `server/label_blocks.py` (pure Python; unit tests in `server/tests/test_silkscreen.py` and `test_label_blocks.py` run without Altium). The links are drawn by the `edit_silk_graphics` bridge command, which adds or removes free overlay tracks, arcs and centred stroke text in one undo step and checks each new primitive with the silk rules. Altium's Silk To Silk rule only checks text against other silk (a free track crossing another free track or arc passes), so a marker letter must clear its shape. It measures stroke text by its ink: Altium's bounding box runs half a stroke beyond the strokes, and its silk rules check the strokes. The Board Outline Clearance rule is the exception: it measures from the bounding box, and its text clearance comes from the rule's per-object table (`GetClearance(eObjectClearanceID_Text, eObjectClearanceID_OutlineEdge)`), not its generic Gap.
- Altium pitfalls the tools work around:
- - Batch DRC checks a cached copy of each text's stroke geometry, and a scripted move or resize does not refresh it. The batch DRC then reports collisions where the text used to be and can miss them where it is now (on the test board, 457 phantom silk-to-silk hits, while every label passed `Rule.ActualCheck`). `set_designator_positions` and `auto_place_silkscreen` rebuild each designator they touch with `SetState_XSizeYSize` inside Begin/EndModify. Text moved by other scripts, such as the GUI auto placer, probably has the same problem (not tested).
- - `Pad.BoundingRectangleOnLayer(solder mask)` can be offset from the pad for some custom pad shapes (a SOT-89 tab was 55 mil off). The export takes the union with the pad's own bounding rectangle and flags the pad, and the model then treats it as a plain rectangle.
- ### PCB Footprint Library
- - `create_pcb_footprint`: Create a new PCB footprint in the currently active .PcbLib document. Supports SMD pads (Rect, Round, Oval shapes) defined in mm relative to the component origin. Auto-generates a courtyard on Mech 15 and silkscreen with a pin 1 indicator (gap in the top-left corner), or accepts explicit courtyard dimensions. Contributed by [coffeedust](https://github.com/coffeedust) ([PR #7](https://github.com/coffeenmusic/altium-mcp/pull/7)).
- - `get_footprint_primitives`: Inventory a .PcbLib (per-footprint primitive counts) or dump complete footprint geometry - pads with full stack/hole detail, tracks, arcs, fills, texts, regions - in mils, relative to the footprint origin (also for the footprint shown in the editor). Pads also report their paste and solder mask mode and expansion and whether they are `locked`. The reference source when recreating or verifying footprints. A dumped footprint also lists its 3D bodies (`bodies_3d`: model file, whether it is embedded, its X/Y offset, standoff and overall height, layer, model rotation X/Y/Z and Z offset); the bodies themselves are not recreated. The rotations and Z offset are read from the saved library file, because `IPCB_Model.GetState` returns them through out parameters that DelphiScript never receives. A body that is not saved yet has them as null (`placement` says which).
- - `create_footprints_batch`: Create many footprints in one script run from a plain-text spec file: SMD + through-hole pads (holes, slots, plating, rotation, full pad stack, paste and solder mask expansion), tracks, arcs, fills, texts, regions on any layer, and 3D models. Every pad it creates is locked. Records beyond the original set:
- - `PAD|...|bot_shape|paste_mode|paste_expansion|mask_mode|mask_expansion`: optional paste and solder mask expansion at the end of a PAD record. Modes are TMaskExpansionMode ints: 1 rule, 2 manual (expansion in mils). Mode 0 (no mask) cannot be set on a pad by script: the mode setters ignore it, and the paste-enable and tenting properties are not kept, so it is reported as a problem. Manual values are set through the pad cache, because the `PasteMaskExpansion`/`SolderMaskExpansion` setters stop the script.
- - `MODEL3D|<STEP file>|<layer>|<rot_x>|<rot_y>|<rot_z>|<z_offset>[|<x>|<y>[|<embed 1/0>]]`: add a 3D body from a STEP file, embedded unless embed is 0.
- - `EDITFOOTPRINT|<name>`: add `MODEL3D` records to an existing footprint; it never creates a footprint, and other records under it are reported and ignored.
- Altium keeps the footprint shown in the library editor on the library board, offset by the library origin, and writes it back when another footprint is shown. So a model for the shown footprint is added to the board, at that offset; added to the footprint itself, it would be lost. Round-trip verified against complete production SMD and through-hole libraries. Like `create_symbols_batch`, it leaves the library modified and unsaved, and an `FPLIB|<path>` line focuses the open library rather than reloading it.
- ### Both
- - `get_screenshot`: Take a screenshot of exactly one thing in Altium, returned as a proper image the agent can see. `target` says what: `current` (the window as it is, the default; nothing is switched), `document` (the active document's editing area), `document:<file name or path>` (that document's editing area; only an open one unless `open_if_closed`, the previously active document is brought back afterwards and a document opened for the capture is closed again when unchanged), `dialog` (the topmost Altium dialog or popup), `panel:<name>` (e.g. `panel:Projects`) or `region:x,y,w,h` (a rectangle inside Altium's main window, in pixels of a `current` capture; nothing outside Altium is ever captured). `zoom_to` (designators) zooms a board to those components first; given on its own it means `view_type` 'pcb'. `zoom_to="board"` fits the whole board outline instead. Every capture is also saved in the server's own folder (`screenshots` beside config.json, the newest 50 kept) and the reply gives it as `saved_path`. `hide_hud=True` moves the mouse pointer off the document view for the capture and back after, so Altium's heads-up coordinate display is not captured; it is off by default because it moves the user's real pointer. With the screen locked the capture fails with an error saying so. The metadata says what was captured (`captured_kind`, `captured_document`, `view_type`) and whether anything was switched, opened or closed. The old `view_type` 'pcb'/'sch' still works as before. Altium comes to the front for about a second for the capture, then the window that was in front gets the foreground back. An Altium dialog over the captured area refuses the capture and is named in the error; a floating panel there (Messages, after `run_drc`) gives a warning, or is hidden for the capture with `hide_floating_panels`.
- - `get_altium_windows`: List Altium's own dialogs and floating panels (hwnd, class, title, rectangle, whether a dialog is modal): the windows that can lie over a board in a screenshot or keep Altium waiting.
- - `dismiss_dialog`: Close an open Altium dialog, given by its hwnd or title, as its close box does, so whatever it asks about is left unapplied. It never presses a button (that would commit the dialog, and a dialog the user is filling in looks the same). Only Altium's own dialogs, never its main window, a panel or another program.
- ### Scripting / Development
- - `run_altium_script`: Run a DelphiScript snippet in an **isolated sandbox** and get back a step-by-step log, the script's result, and - when a script fails - Altium's own error message with the line in your script. Each run is written to a fresh copy of `SandboxScript/Sandbox.pas` with a unique file name and started with `ScriptingSystem:RunScriptFile`, so a script that failed earlier can never be re-run from Altium's script editor. Errors inside the script (undeclared identifiers, calls on nil, bad conversions) are caught and reported without blocking Altium; syntax errors are reported from Altium's error dialog, which the tool answers before stopping the debugger (`-REditScript:Stop`) and confirming with a probe run that the next script will work. The other MCP tools recover the same way when one of their own commands gets stuck. Only scripts the MCP started are ever stopped: a script you are running or debugging in Altium is left alone, and the tool says Altium is busy instead. Scripts may start with their own `var` block, followed by their own functions and procedures; `Exit` ends the script and still returns its result. Assignments to undeclared names, reserved words and directives used as names (`Index`, `Read`, `Default`, ...), and comparisons next to `and`/`or` or after `not` without parentheses are refused before Altium is called, since Altium's own messages for them do not say what is wrong; `skip_lint=True` skips the reserved-word and precedence checks for a false positive. The script's `var` block is global, so declaring a name the sandbox already declares (`var S1 : Integer;`, `MM`, ...) is refused too: use the sandbox's variable without declaring it, or pick another name. The template provides `MM()`, `OpenSchDoc()` and `SaveDoc()` helpers, and `FmtNum()`, `FmtMM()`, `ParseNum()` and `ParseMM()` for numbers with a decimal dot whatever the Windows locale. Before each run the Altium documents the script names by their full path are copied to a per-user folder (`~/.altium-mcp/snapshots` by default), or those given in `snapshot`; a script that works on `GetCurrentPCBBoard` or the focused document names none, and the result then says that nothing was snapshotted. While waiting it closes blocking Altium dialogs (only windows owned by `X2.EXE`) and returns their titles in `dismissed_dialog_titles` - close your own Altium dialogs before running scripts, since an open dialog of yours may be closed too.
- - `rollback_altium_script`: Undo a `run_altium_script` run: close the documents it snapshotted in Altium without saving, put the copies from before the run back, and reopen the ones that were open. A file changed on disk since the run (saved later by you or by another run) is always refused, and the snapshot copies are listed so you can restore them by hand. A document that had unsaved changes in Altium before the run, or has unsaved changes at rollback (also one the script itself left unsaved, which you may have kept editing), is refused unless `discard_unsaved=True`, since those changes would be lost. When Altium is not running the files are restored straight after the on-disk check, without starting it. A project is refused while another of its open documents has unsaved changes, since closing it would ask to save them.
- - `ensure_altium_script_skill`: Check whether the [altium-script skill](https://github.com/coffeenmusic/altium-scripts-skill) (Altium DelphiScript API reference, examples, and conventions) is installed, and install it on request. Skills load at client startup, so a newly installed skill appears after a restart.
- ### Server Status
- - `get_server_status`: Check the status of the MCP server, including paths to Altium and script files
- ## How It Works
- The server communicates with Altium Designer using a scripting bridge:
- 1. It writes command requests to `C:\Users\Public\altium_mcp\request.json`
- 2. It launches Altium with instructions to run the bridge script: the units of `server/AltiumScript/Altium_API.PrjScr` merged into one file in `C:\Users\Public\altium_mcp\bridge`, named after its content so Altium never runs a stale copy it still holds open (`ScriptingSystem:RunScriptFile`)
- 3. The script processes the request and writes results to `C:\Users\Public\altium_mcp\response.json`
- 4. The server reads and returns the response
- **Why one merged file, not the script project.** Running a script *project* (`ScriptingSystem:RunScript` with `ProjectName`) makes Altium create a hidden copy of every form in the script projects on the user's menus, and never free it. On one machine with 14 such forms that was about 105 Windows USER objects per call. Windows caps a process at 10,000 (`USERProcessHandleQuota`). Near the cap Altium shows "System Error. Code: 1158 ... used all of its system allowance of handles for Window Manager objects" and then crashes, losing unsaved work, after about 90 calls. Running a single script file (`RunScriptFile`) or script text (`RunScriptText`) leaks nothing, so `server/script_bundle.py` merges the units into one file: global `var`/`const` blocks first, then each routine after the routines it calls (a single file must define a routine before its first use). The bundle is rebuilt whenever a unit changes. The project is still the source to edit, and the fallback if bundling fails.
- When adding bridge code: start every routine, and its `begin` and final `end;`, at column 0, and don't let routines call each other in a cycle (the bundle has no forward declarations). `tests/test_script_bundle.py` checks the real units. The sandbox runs its script as a file too.
- Altium's script engine also leaks memory: every property read of a board object costs roughly 100-200 bytes that are never freed. On a 40,000-object board that is about 25 MB per silkscreen export and 50 MB per full silkscreen check, so a long session of exports grows Altium by gigabytes until it runs out of memory and dies with unsaved work. The bridge scripts read each object's properties once and skip objects early; the silkscreen tools reuse one board export for up to 15 minutes and update it themselves after their own moves and link graphics.
- As a backstop, the server checks Altium before every call and refuses when it is within 1,000 USER objects of the cap (the user's own menu scripts still leak each time they run) or using more than half of the machine's RAM, asking for a save and restart.
- Files exchanged with the scripts are read and written the way Altium does: in the Windows ANSI code page, or as UTF-8 when the file starts with a byte-order mark.
- ## References
- - Get scripts' project path from Jeff Collins and William Kitchen's stripped down version
- - BlenderMCP: I got inspired by hearing about MCP being used in Blender and used it as a reference. https://github.com/ahujasid/blender-mcp
- - Used CopyDesignatorsToMechLayerPair script by Petar Perisin and Randy Clemmons for reference on how to .Replicate objects (used in layout duplicator)
- - Petar Perisin's Select Bad Connections Script: For understanding how to walk pcb primitives (track, arc, via, etc) connected to a pad
- - Matija Markovic and Petar Perisin Distribute Script: For understanding how to properly let the GUI know when I've updated tracks' nets
- - Petar Perisin's Room from Poly: Used as reference to detect poly to pad overlap since I couldn't get more tradition methods to work.
- - Petar Perisin's Layer Panel Script: Used as reference for getting layers and changing layer visibility
- - Jeff Collins has an XIA_Release_Manager.pas script that taught me the art of the Output Job. See his post on the Altium Forums: https://forum.live.altium.com/#/posts/189423
- ## Contributors
- - [SiboVG](https://github.com/SiboVG) — the PCB editing and checking tools (`run_drc`, `create_pcb_rule`, `place_vias`, `place_polygon_pour`, `place_cutout`, `repour_polygons`, `get_pour_report`, `check_routing`, `route_track`), `check_schematic` and `edit_schematic`, and much of the server's reliability: sandbox runs that report Altium's errors and recover, commands kept in order across servers, finding Altium from the registry, log rotation, the `mcp` 1.30 upgrade and CI ([25 PRs](https://github.com/coffeenmusic/altium-mcp/pulls?q=is%3Apr+is%3Amerged+author%3ASiboVG))
- - [daescobarh](https://github.com/daescobarh) — project validation tools (`get_project_info`, `get_project_components`, `get_erc_violations`, `get_board_summary`, `get_component_primitives`, `get_outjob_settings`) and safer dialog dismissal ([PR #18](https://github.com/coffeenmusic/altium-mcp/pull/18))
- - [Glomma](https://github.com/Glomma) — `outjob_path` for the OutJob tools and PDF containers that really publish ([PR #28](https://github.com/coffeenmusic/altium-mcp/pull/28)), plus fixes to the bridge and the bootstrap venv ([PR #26](https://github.com/coffeenmusic/altium-mcp/pull/26), [PR #27](https://github.com/coffeenmusic/altium-mcp/pull/27))
- - [Dziersk](https://github.com/Dziersk) — automatic recovery from a stuck script ([PR #23](https://github.com/coffeenmusic/altium-mcp/pull/23)) and sandbox safeguards against calls that crash Altium ([PR #36](https://github.com/coffeenmusic/altium-mcp/pull/36))
- - [coffeedust](https://github.com/coffeedust) — `create_pcb_footprint` tool for PcbLib automation ([PR #7](https://github.com/coffeenmusic/altium-mcp/pull/7))
- - [Dcatfly](https://github.com/Dcatfly) — `get_screenshot` captures the whole window on scaled displays ([PR #24](https://github.com/coffeenmusic/altium-mcp/pull/24))
- - [SC5KSystems](https://github.com/SC5KSystems) — the server fails fast on a broken venv instead of hanging for 60 seconds ([PR #15](https://github.com/coffeenmusic/altium-mcp/pull/15))
- - [fwolter](https://github.com/fwolter) — Fix JSON parsing error when the decimal separator is a comma ([PR #3](https://github.com/coffeenmusic/altium-mcp/pull/3)), and a typo fix ([PR #1](https://github.com/coffeenmusic/altium-mcp/pull/1))
- - [dishishshawn](https://github.com/dishishshawn) — the supported Python versions in this README ([PR #63](https://github.com/coffeenmusic/altium-mcp/pull/63))
- Thanks also to everyone who has [reported issues](https://github.com/coffeenmusic/altium-mcp/issues?q=is%3Aissue), especially [RSO-KME](https://github.com/RSO-KME) for detailed testing reports.
- ## Disclaimer
- This is a third-party integration and not made by Altium. Made by [coffeenmusic](https://x.com/coffeenmusic)
- # TODO:
- - Change selection filter:
- - `scripts-libraries\Scripts - PCB\FilterObjects\`
- - `scripts-libraries\Scripts - SCH\SelectionFilter\`
- - Show/Hide Panels: `DXP/ReportPCBViews.pas`
- - Move cursor to position: IPCB_Board.XCursor, IPCB_Board.YCursor
- - Add get schematic & pcb library path for footprint.
- - log response time of each tool
- - Add go to schematic sheet
- - Go to sheet with component designator
- - Board.ChooseLocation(x, y, 'Test');
- - Zoom to selected objects:
- - Change Schematic Selection Filter: SelectionFilter.pas
- - How can I read through components from libraries in Components panel?
- TODO Tests:
- Need to add the following test units
- - `get_pcb_layers`
- - `set_pcb_layer_visibility`
- - `layout_duplicator`
- - `get_screenshot`
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.