Skip to content
Back to search

altium-designer-mcp

MCP server for AI-assisted management of Altium Designer component libraries

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

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/embedded-society/altium-designer-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/embedded-society/altium-designer-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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/embedded-society--altium-designer-mcp/badge.svg)](/listings/embedded-society--altium-designer-mcp)

HTML

<a href="/listings/embedded-society--altium-designer-mcp"><img src="/api/listings/embedded-society--altium-designer-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> **[Client Setup](docs/CLIENT_SETUP.md)** — verified configuration for Claude Code, Claude > Desktop, Google Antigravity, Cursor, VS Code, GitHub Copilot CLI, Windsurf, Cline, Roo Code, > Kiro, JetBrains, Zed, Gemini CLI, Codex CLI, Continue, Goose, OpenCode and any other stdio > MCP client, plus troubleshooting — on **Windows**, **Linux**, and **macOS**. > > **[Using the server](docs/USAGE.md)** — what to ask for once it is connected: example > workflows, prompts and tips, identical for every client.

---

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 · 649 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.

  1. # altium-designer-mcp
  2. [![CI](https://github.com/embedded-society/altium-designer-mcp/actions/workflows/ci_main.yml/badge.svg)](https://github.com/embedded-society/altium-designer-mcp/actions/workflows/ci_main.yml)
  3. [![codecov](https://codecov.io/gh/embedded-society/altium-designer-mcp/branch/main/graph/badge.svg)](https://app.codecov.io/gh/embedded-society/altium-designer-mcp)
  4. [![altium-designer-mcp MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/embedded-society/altium-designer-mcp/badges/score.svg)](https://glama.ai/mcp/servers/embedded-society/altium-designer-mcp)
  5. [![altium-designer-mcp MCP server on mcprush](https://mcprush.com/badge/altium-designer-mcp/compact.svg)](https://mcprush.com/to/altium-designer-mcp?ref=badge)
  6. **Let an AI build your Altium libraries — it does the engineering, this tool writes the files.**
  7. An MCP server that gives AI assistants (Claude Code, Claude Desktop, Cursor, Antigravity, VS Code Copilot — any MCP client) file I/O
  8. and primitive-placement tools for Altium Designer `.PcbLib` (footprint) and `.SchLib` (symbol)
  9. libraries — so the AI can create and maintain *any* component, not just pre-programmed packages.
  10. ---
  11. ## The Problem
  12. Building Altium component libraries by hand is slow and repetitive — every footprint means
  13. looking up IPC-7351B pad sizes, courtyards, and silkscreen, then placing each primitive by
  14. hand. AI assistants are excellent at exactly that reasoning, but they **cannot write Altium's
  15. binary `.PcbLib`/`.SchLib` files** — an undocumented OLE compound format that is easy to
  16. corrupt, and Altium silently refuses to open a malformed file.
  17. | Approach | Problem |
  18. |----------|---------|
  19. | Draw every footprint by hand in Altium | Slow and repetitive; the AI can't touch the file |
  20. | Ask an AI to emit the binary file directly | It produces a corrupt file Altium won't open |
  21. | Pre-programmed footprint generators | Only the package types someone coded in advance |
  22. ---
  23. ## The Core Idea
  24. **The AI handles the intelligence. The tool handles file I/O.**
  25. | Responsibility | Owner |
  26. |---------------|-------|
  27. | IPC-7351B calculations | AI |
  28. | Package layout decisions | AI |
  29. | Style choices | AI |
  30. | Datasheet interpretation | AI |
  31. | Reading/writing Altium files | This tool |
  32. | Primitive placement | This tool |
  33. | STEP model attachment | This tool |
  34. This means the AI can create **any footprint** — not just pre-programmed package types.
  35. See [docs/VISION.md](docs/VISION.md) for the full architectural rationale.
  36. ---
  37. ## Who Is This For?
  38. Anyone who **builds or maintains Altium component libraries** and uses an **MCP-capable AI
  39. assistant**. The AI does the engineering (datasheet → dimensions → style); this server lets it
  40. read and write the actual `.PcbLib` / `.SchLib` files.
  41. | If you… | Then… |
  42. |---------|-------|
  43. | Use Claude Code, Claude Desktop, Cursor, Antigravity, VS Code + Copilot — [any MCP client](docs/CLIENT_SETUP.md) — and design in Altium | ✅ This is for you |
  44. | Want pre-baked generators for a fixed set of packages | ❌ Not this — the point is *any* component |
  45. | Don't use Altium | ❌ Not applicable |
  46. ---
  47. ## Quick Start
  48. > **[Client Setup](docs/CLIENT_SETUP.md)** — verified configuration for Claude Code, Claude
  49. > Desktop, Google Antigravity, Cursor, VS Code, GitHub Copilot CLI, Windsurf, Cline, Roo Code,
  50. > Kiro, JetBrains, Zed, Gemini CLI, Codex CLI, Continue, Goose, OpenCode and any other stdio
  51. > MCP client, plus troubleshooting — on **Windows**, **Linux**, and **macOS**.
  52. >
  53. > **[Using the server](docs/USAGE.md)** — what to ask for once it is connected: example
  54. > workflows, prompts and tips, identical for every client.
  55. ---
  56. ## How It Works
  57. ```text
  58. ┌─────────────────────────────────────────────────────────────────────────────┐
  59. │ AI-ASSISTED COMPONENT CREATION │
  60. │ │
  61. │ Engineer AI MCP Server │
  62. │ │ │ │ │
  63. │ │ "Create 0603 resistor" │ │ │
  64. │ ├────────────────────────►│ │ │
  65. │ │ │ │ │
  66. │ │ │ AI reasons about: │ │
  67. │ │ │ • IPC-7351B pad sizes │ │
  68. │ │ │ • Courtyard margins │ │
  69. │ │ │ • Silkscreen/symbol style │ │
  70. │ │ │ │ │
  71. │ │ │ write_pcblib(primitives) │ │
  72. │ │ ├─────────────────────────────►│ │
  73. │ │ │ │ Writes │
  74. │ │ │ │ .PcbLib + │
  75. │ │ │ write_schlib(symbol) │ .SchLib files │
  76. │ │ ├─────────────────────────────►│ │
  77. │ │ │◄─────────────────────────────┤ │
  78. │ │ │ { status: "success" } │ │
  79. │ │ │ │ │
  80. │ │ "Done! Footprint │ │ │
  81. │ │ and symbol created" │ │ │
  82. │ │◄────────────────────────┤ │ │
  83. │ │
  84. └─────────────────────────────────────────────────────────────────────────────┘
  85. ```
  86. ---
  87. ## MCP Tools
  88. The server exposes **34 tools**, working on both `.PcbLib` (footprints) and
  89. `.SchLib` (symbols). Every tool's full parameters and examples live in
  90. **[docs/TOOLS.md](docs/TOOLS.md)** — this is the categorised overview.
  91. ### Read & write
  92. | Tool | Purpose |
  93. |------|---------|
  94. | [`read_pcblib`](docs/TOOLS.md#read_pcblib) | Read footprints from a `.PcbLib`. |
  95. | [`write_pcblib`](docs/TOOLS.md#write_pcblib) | Write footprints to a `.PcbLib`. |
  96. | [`read_schlib`](docs/TOOLS.md#read_schlib) | Read symbols from a `.SchLib`. |
  97. | [`write_schlib`](docs/TOOLS.md#write_schlib) | Write symbols to a `.SchLib`. |
  98. ### Inspect & visualise
  99. | Tool | Purpose |
  100. |------|---------|
  101. | [`list_components`](docs/TOOLS.md#list_components) | List component names (paginated). |
  102. | [`get_component`](docs/TOOLS.md#get_component) | Get one component's full data. |
  103. | [`search_components`](docs/TOOLS.md#search_components) | Search across libraries by regex/glob. |
  104. | [`component_exists`](docs/TOOLS.md#component_exists) | Check whether components exist. |
  105. | [`render_footprint`](docs/TOOLS.md#render_footprint) | ASCII-art preview of a footprint. |
  106. | [`render_symbol`](docs/TOOLS.md#render_symbol) | ASCII-art preview of a symbol. |
  107. | [`extract_style`](docs/TOOLS.md#extract_style) | Extract styling from an existing library. |
  108. ### Compare
  109. | Tool | Purpose |
  110. |------|---------|
  111. | [`diff_libraries`](docs/TOOLS.md#diff_libraries) | Compare two library files. |
  112. | [`compare_components`](docs/TOOLS.md#compare_components) | Diff two specific components. |
  113. ### Edit in place
  114. | Tool | Purpose |
  115. |------|---------|
  116. | [`update_component`](docs/TOOLS.md#update_component) | Update a component, preserving its position. |
  117. | [`update_pad`](docs/TOOLS.md#update_pad) | Update one pad's properties. |
  118. | [`update_primitive`](docs/TOOLS.md#update_primitive) | Update one primitive (track/arc/text/fill/region). |
  119. | [`batch_update`](docs/TOOLS.md#batch_update) | Batch updates across all components. |
  120. | [`reorder_components`](docs/TOOLS.md#reorder_components) | Reorder components in a library. |
  121. | [`manage_schlib_parameters`](docs/TOOLS.md#manage_schlib_parameters) | List/get/set/remove SchLib parameters. |
  122. | [`manage_schlib_footprints`](docs/TOOLS.md#manage_schlib_footprints) | Manage footprint links in SchLib symbols. |
  123. ### Manage components
  124. | Tool | Purpose |
  125. |------|---------|
  126. | [`delete_component`](docs/TOOLS.md#delete_component) | Delete one or more components. |
  127. | [`copy_component`](docs/TOOLS.md#copy_component) | Duplicate a component within a library. |
  128. | [`rename_component`](docs/TOOLS.md#rename_component) | Rename a component (atomic). |
  129. | [`copy_component_cross_library`](docs/TOOLS.md#copy_component_cross_library) | Copy a component to another library. |
  130. | [`bulk_rename`](docs/TOOLS.md#bulk_rename) | Pattern-based multi-rename. |
  131. ### Library operations
  132. | Tool | Purpose |
  133. |------|---------|
  134. | [`merge_libraries`](docs/TOOLS.md#merge_libraries) | Merge multiple libraries into one. |
  135. | [`write_libpkg`](docs/TOOLS.md#write_libpkg) | Write a `.LibPkg` project grouping libraries for IntLib compilation. |
  136. | [`export_library`](docs/TOOLS.md#export_library) | Export to JSON/CSV. |
  137. | [`import_library`](docs/TOOLS.md#import_library) | Import from JSON (inverse of export). |
  138. | [`validate_library`](docs/TOOLS.md#validate_library) | Validate for common issues. |
  139. | [`repair_library`](docs/TOOLS.md#repair_library) | Remove orphaned data. |
  140. | [`extract_step_model`](docs/TOOLS.md#extract_step_model) | Extract embedded STEP 3D models. |
  141. ### Backups & safety
  142. | Tool | Purpose |
  143. |------|---------|
  144. | [`list_backups`](docs/TOOLS.md#list_backups) | List automatic backups. |
  145. | [`restore_backup`](docs/TOOLS.md#restore_backup) | Restore from a backup. |
  146. ## Primitive Types
  147. ### Footprint Primitives (PcbLib)
  148. | Primitive | Description |
  149. |-----------|-------------|
  150. | **Pad** | SMD or through-hole pad with designator, position, size, shape, layer (see Pad Shapes below), power-plane thermal relief, and its own polygon-connect style |
  151. | **Via** | Vertical interconnect with layer span, hole size, and thermal relief |
  152. | **Track** | Line segment on any layer (silkscreen, assembly, etc.) |
  153. | **Arc** | Arc or circle on any layer |
  154. | **Region** | Filled polygon (courtyard, copper pour), with optional hole contours |
  155. | **Text** | Text string with font, size, position, layer |
  156. | **Fill** | Filled rectangle on any layer |
  157. | **ComponentBody** | 3D model reference (embedded STEP models) |
  158. #### Pad Shapes and Pin 1 Indicator
  159. The `shape` property on pads controls the copper shape. Use this to indicate pin 1:
  160. | Shape | Value | Usage |
  161. |-------|-------|-------|
  162. | Rectangle | `"rectangle"` | **Pin 1 indicator** — use for the first pad to distinguish it visually |
  163. | Rounded Rectangle | `"rounded_rectangle"` | Default for SMD pads (most common) |
  164. | Round | `"round"` or `"circle"` | Circular pads, default for through-hole (both values are equivalent) |
  165. | Oval | `"oval"` | Oblong pads for constrained spaces |
  166. | Octagonal | `"octagonal"` | Eight-sided pads (chamfered corners) |
  167. **Example — marking pin 1 with a rectangular pad:**
  168. ```json
  169. {
  170. "pads": [
  171. { "designator": "1", "x": -0.75, "y": 0, "width": 0.9, "height": 0.95, "shape": "rectangle" },
  172. { "designator": "2", "x": 0.75, "y": 0, "width": 0.9, "height": 0.95, "shape": "rounded_rectangle" }
  173. ]
  174. }
  175. ```
  176. This follows the IPC-7351 convention where pin 1 has a distinct shape (typically rectangular or square corners) while other pads use rounded corners.
  177. ### Symbol Primitives (SchLib)
  178. | Primitive | Description |
  179. |-----------|-------------|
  180. | **Pin** | Component pin with name, designator, electrical type, orientation |
  181. | **Rectangle** | Filled or unfilled rectangle (component body) |
  182. | **RoundRect** | Rounded rectangle with corner radii |
  183. | **Line** | Single line segment |
  184. | **Polyline** | Multiple connected line segments |
  185. | **Polygon** | Filled polygon with border and fill colours |
  186. | **Arc** | Arc or circle |
  187. | **Pie** | Filled circular sector (arc geometry plus fill) |
  188. | **Image** | Embedded or linked raster picture with a bounding box |
  189. | **Ellipse** | Ellipse or circle (filled or unfilled) |
  190. | **EllipticalArc** | Elliptical arc segment with fractional radii |
  191. | **Bezier** | Cubic Bezier curve (4 control points) |
  192. | **Label** | Text string (RECORD=4) — the only free text on a symbol |
  193. | **IeeeSymbol** | IEEE symbol glyph (RECORD=3): a dot, a clock, an active-low input, … |
  194. | **TextFrame** | Bordered multi-line text box (word-wrap, alignment) |
  195. | **Parameter** | Component parameter (Value, Part Number, etc.) |
  196. | **FootprintModel** | Reference to a footprint in a PcbLib |
  197. ### Standard Altium Layers
  198. Common layers for footprints (each has a Bottom equivalent):
  199. | Layer | Usage |
  200. |-------|-------|
  201. | Top Layer | Copper pads (SMD) |
  202. | Bottom Layer | Bottom copper pads |
  203. | Multi-Layer | Through-hole pads (all copper layers) |
  204. | Top Overlay | Silkscreen |
  205. | Top Paste | Solder paste stencil |
  206. | Top Solder | Solder mask openings |
  207. | Top Assembly | Assembly outline (documentation) |
  208. | Top Courtyard | Courtyard boundary (IPC-7351) |
  209. | Top 3D Body | 3D model outline |
  210. Additional layers supported:
  211. | Layer | Usage |
  212. |-------|-------|
  213. | Mid-Layer 1–30 | Internal copper layers |
  214. | Internal Plane 1–16 | Power/ground planes |
  215. | Mechanical 1–32 | User-defined mechanical layers |
  216. | Drill Guide | Drill hole markers |
  217. | Drill Drawing | Drill chart/table |
  218. | Keep-Out Layer | Routing exclusion zones |
  219. A layer may be named as Altium spells it (`Top Overlay`, `Mechanical 13`) or in camel
  220. case (`TopOverlay`, `Mechanical13`), in any case; every tool accepts the same spellings.
  221. ---
  222. ## Installation
  223. **Prebuilt binaries** for Linux (x86_64), macOS (aarch64) and Windows (x86_64) are on the
  224. [Releases page](https://github.com/embedded-society/altium-designer-mcp/releases) — each
  225. archive bundles a setup README plus [`docs/CLIENT_SETUP.md`](docs/CLIENT_SETUP.md), which
  226. wires the server into every MCP client we know of. The Linux binary needs glibc 2.34 or newer:
  227. Ubuntu 22.04, Debian 12, RHEL 9 (and its free rebuilds, AlmaLinux and Rocky Linux 9) and later.
  228. **Claude Desktop users** need no archive at all: install the one-click extension
  229. `altium-designer-mcp.mcpb` from the same page (older builds: the identical
  230. `altium-designer-mcp.dxt`) via Settings → Extensions → Advanced settings →
  231. Install Extension… — see [CLIENT_SETUP.md § Claude Desktop](docs/CLIENT_SETUP.md#claude-desktop).
  232. **Code signing policy**: [docs/CODE_SIGNING_POLICY.md](docs/CODE_SIGNING_POLICY.md). The
  233. Windows binaries are to be signed through SignPath Foundation; until that is approved
  234. they are unsigned, and every release carries a signed build-provenance attestation.
  235. **In a container** — for a Linux box, a NAS or a CI job that generates libraries into a
  236. mounted folder (Altium itself never needs to be inside): the repository's `Dockerfile`
  237. produces the same `--locked` release build as the published binaries.
  238. ```bash
  239. docker build -t altium-designer-mcp .
  240. docker run -i --rm -v /path/to/libraries:/libraries altium-designer-mcp
  241. ```
  242. The mounted `/libraries` folder is the container's whole allow-list. In a client's
  243. configuration that is `"command": "docker"` with
  244. `"args": ["run", "-i", "--rm", "-v", "/path/to/libraries:/libraries", "altium-designer-mcp"]`.
  245. To build from source instead, see
  246. [CONTRIBUTING.md § Development Setup](CONTRIBUTING.md#development-setup); an optimised
  247. binary comes from `cargo build --release` and lands at `target/release/altium-designer-mcp`.
  248. ### Verifying a downloaded release
  249. Released archives are built by GitHub Actions and carry a signed
  250. [SLSA build provenance](https://slsa.dev/) attestation, so a download can be traced
  251. back to the workflow run and commit that produced it:
  252. ```bash
  253. gh attestation verify <archive> --repo embedded-society/altium-designer-mcp
  254. sha256sum --check --ignore-missing SHA256SUMS.txt
  255. ```
  256. The binaries are not code-signed, so Windows SmartScreen and macOS Gatekeeper warn on
  257. first run (on macOS, right-click → Open). The attestation is the stronger check.
  258. See [docs/RELEASING.md](docs/RELEASING.md) for how releases are produced.
  259. ### Command-Line Usage
  260. ```bash
  261. altium-designer-mcp [OPTIONS] [CONFIG_FILE]
  262. ```
  263. | Option | Description |
  264. |--------|-------------|
  265. | `CONFIG_FILE` | Path to configuration file (optional, uses default location if omitted) |
  266. | `--allow <DIR>...` | Grant access to library folders directly (repeatable). Adds to the config file's `allowed_paths`, and works with no config file at all — the other settings then take their defaults |
  267. | `--ansi-code-page <PAGE>` | The Windows ANSI code page new footprint names are written in, tried first when a library's page is detected, and used for a library that shows none (`936` for GBK, `1250`, `1252`, …); overrides `ansi_code_page` in the config file |
  268. | `--http <ADDR>` | Serve the MCP Streamable HTTP transport on this address (for example `127.0.0.1:8080`) at the path `/mcp`, instead of stdio. A non-loopback address is refused unless a bearer token is set in `ALTIUM_DESIGNER_MCP_HTTP_TOKEN`. See [`docs/CLIENT_SETUP.md` § HTTP transport](docs/CLIENT_SETUP.md#http-transport) |
  269. | `--http-allow-origin <ORIGIN>...` | A browser origin allowed to reach the HTTP transport besides the local ones (repeatable) |
  270. | `-v`, `--verbose` | Increase logging verbosity (`-v` info, `-vv` debug, `-vvv` trace) |
  271. | `-q`, `--quiet` | Decrease logging verbosity (only show errors) |
  272. | `-h`, `--help` | Print help information |
  273. | `-V`, `--version` | Print version information |
  274. ### Connecting an AI client
  275. Every MCP client needs the same two absolute paths — the binary and your config file — and
  276. differs only in where they are written. The standard block most clients read:
  277. ```json
  278. {
  279. "mcpServers": {
  280. "altium": {
  281. "command": "/usr/local/bin/altium-designer-mcp",
  282. "args": ["/home/you/.altium-designer-mcp/config.json"]
  283. }
  284. }
  285. }
  286. ```
  287. Where that goes for Claude Desktop, Cursor, VS Code, Windsurf, Cline, Zed, JetBrains,
  288. Gemini CLI, Codex CLI and the rest — and what to do when a client cannot see the server —
  289. is in [docs/CLIENT_SETUP.md](docs/CLIENT_SETUP.md). Use absolute paths: clients do not
  290. search `PATH` or expand `~` for you.
  291. ---
  292. ## Configuration
  293. The server reads one JSON file — or none: `altium-designer-mcp --allow <DIR>` grants
  294. folders on the command line and runs on defaults for everything else, which is how the
  295. Claude Desktop extension starts it. Configuration file location:
  296. - **Linux/macOS:** `~/.altium-designer-mcp/config.json`
  297. - **Windows:** `%USERPROFILE%\.altium-designer-mcp\config.json`
  298. ```json
  299. {
  300. "allowed_paths": [
  301. "/path/to/your/altium/libraries",
  302. "/another/library/path"
  303. ],
  304. "logging": {
  305. "level": "warn"
  306. }
  307. }
  308. ```
  309. ### Configuration Options
  310. | Option | Description |
  311. |--------|-------------|
  312. | `allowed_paths` | Array of directory paths where library files can be accessed; `--allow` adds to it (default when neither grants anything: the current working directory) |
  313. | `logging.level` | Log level: trace, debug, info, warn, error (default: warn) |
  314. | `logging.audit_log_path` | Path to an append-only JSON-lines audit log of destructive operations (default: null — no audit log is written) |
  315. | `rate_limit.max_burst` | Maximum burst of mutating operations before throttling; read-only tools are never rate limited (default: 120) |
  316. | `rate_limit.refill_per_sec` | Token-bucket refill rate for mutating operations, in tokens per second (default: 30.0) |
  317. | `ansi_code_page` | The Windows ANSI code page new footprint names are written in: 874, 932, 936, 949, 950, 1250 to 1258 or 65001. The reader also tries it first when it detects a library's code page, and reads a library that shows none through it. Altium Designer 21 displays a footprint's name from those bytes through the machine's code page, so it should be the code page of the machine whose Altium opens the libraries (default: null — the system's code page on Windows, 1252 elsewhere) |
  318. ---
  319. ## STEP Model Integration
  320. STEP models are **attached**, not generated. The tool links existing STEP files to footprints.
  321. ```json
  322. {
  323. "step_model": {
  324. "filepath": "./3d-models/0603.step",
  325. "x_offset": 0,
  326. "y_offset": 0,
  327. "z_offset": 0,
  328. "rotation": 0
  329. }
  330. }
  331. ```
  332. ### Embedded vs External Models
  333. Altium supports two ways to reference 3D models:
  334. | Type | Storage | Portability |
  335. |------|---------|-------------|
  336. | **Embedded** | STEP data stored inside the .PcbLib file | Fully portable — the model travels with the library |
  337. | **External** | File path reference to a .step file on disk | Not portable — requires the file to exist at the referenced path |
  338. When copying or merging components between libraries:
  339. - **Embedded models** travel with the component — `copy_component_cross_library` and
  340. `merge_libraries` both copy the referenced model streams into the target (a model shared by
  341. several footprints is copied once), so the bodies still resolve after the move.
  342. - **External model references**: `copy_component_cross_library` removes them with a warning by
  343. default, since a path relative to the source library rarely resolves elsewhere — pass
  344. `preserve_external_paths=true` to keep them. `merge_libraries` carries them unchanged.
  345. Embedding a model in the source library is the reliable way to keep 3D data through any copy.
  346. ### Extracting Embedded Models
  347. Use `extract_step_model` to extract embedded STEP data from a library:
  348. ```json
  349. {
  350. "name": "extract_step_model",
  351. "arguments": {
  352. "filepath": "./MyLibrary.PcbLib",
  353. "output_path": "./extracted_model.step"
  354. }
  355. }
  356. ```
  357. For parametric 3D model generation, a dedicated mechanical MCP server is planned as a future project.
  358. ---
  359. ## Automatic Backups
  360. Before any destructive operation (delete, update, merge, batch update), the server automatically
  361. creates a timestamped backup of the target file. Backups use the format:
  362. ```text
  363. MyLibrary.PcbLib.20260125_143022.bak
  364. ```
  365. A backup never replaces another: a second one within the same second is
  366. `MyLibrary.PcbLib.20260125_143022_001.bak`, then `_002`, and so on.
  367. **Backup retention:** The 5 most recent backups per file are kept, and so is the first one
  368. the server made of the file since it started, which holds the file as it was before the
  369. session's changes. Older backups are automatically removed to prevent unbounded disk usage.
  370. **Operations that create backups:**
  371. - `delete_component`
  372. - `update_component`
  373. - `update_pad`
  374. - `update_primitive`
  375. - `rename_component`
  376. - `copy_component`
  377. - `copy_component_cross_library` (target file)
  378. - `merge_libraries` (target file)
  379. - `reorder_components`
  380. - `batch_update`
  381. - `bulk_rename`
  382. - `repair_library`
  383. - `manage_schlib_parameters`
  384. - `manage_schlib_footprints`
  385. - `write_pcblib` / `write_schlib` (when overwriting)
  386. - `import_library` (when overwriting)
  387. - `restore_backup` (the current file, before the chosen backup replaces it)
  388. **Managing backups:** Use `list_backups` to view available backups and `restore_backup` to
  389. recover from a previous version.
  390. **Dry-run support:** These operations support `dry_run=true` to preview changes
  391. without modifying files:
  392. - `delete_component` — preview which components would be deleted
  393. - `update_component` — preview component replacement changes
  394. - `update_pad` / `update_primitive` — preview property changes
  395. - `bulk_rename` — preview name changes
  396. - `repair_library` — preview orphaned references to remove
  397. - `batch_update` — preview library-wide updates
  398. - `copy_component` / `rename_component` / `merge_libraries`
  399. ---
  400. ## Notes
  401. ### Libraries from a Non-Western Windows
  402. Altium stores most names as plain bytes in the Windows code page of the machine that wrote
  403. them, with no record of which page that was. A library authored on a Chinese, Japanese,
  404. Korean, Central European, Cyrillic, Greek, Turkish, Baltic, Hebrew, Arabic, Vietnamese or
  405. Thai Windows therefore reads as mojibake (`£¨0402` for `(0402`) in a tool that assumes
  406. Windows-1252.
  407. This server works out the library's code page from the footprints whose real name is
  408. recorded twice — once as those bytes, once in Unicode — reads every name through it, and
  409. writes it back unchanged, so a rewrite stays byte-identical. Nothing needs configuring to
  410. read or edit such a library.
  411. Two cases are worth knowing:
  412. - **A name your Altium must display.** Altium Designer 21 and earlier show a footprint's
  413. name from those bytes, decoded through the code page of the machine they run on, and
  414. never read the Unicode copy. A new or renamed footprint is therefore written in the
  415. server's own code page — the system's on Windows. When the server runs on a machine with
  416. a different locale from the Altium that opens the libraries, name that page with
  417. `ansi_code_page` in the configuration file or `--ansi-code-page` on the command line
  418. (874, 932, 936, 949, 950, 1250 to 1258, or 65001).
  419. - **A character the page cannot hold.** Altium writes `?` in its place, and so does this
  420. server; the full name is still preserved in the component parameters, as Altium preserves
  421. it, and comes back intact on the next read.
  422. ### Long Component Names
  423. Component names longer than 31 characters are supported. The OLE Compound File format limits
  424. storage names to 31 characters, so longer names are automatically truncated internally while
  425. the full name is preserved in component parameters. This is handled transparently — you can
  426. use any length component name and it will be preserved on read/write roundtrips.
  427. ---
  428. ## Privacy Policy
  429. `altium-designer-mcp` is a local tool and collects nothing.
  430. - **Data collection**: none. The server has no telemetry and no analytics, and it never
  431. contacts any service, including this project's. With `--http` it listens for an MCP
  432. client on the address you give; it still sends nothing anywhere.
  433. - **Usage and storage**: it reads and writes only the library files inside the folders
  434. you grant (`allowed_paths` or `--allow`), plus the timestamped `.bak` copies it makes
  435. beside them before a change. The optional audit log (`logging.audit_log_path`) is a
  436. local file you choose, holding tool names, file names and outcomes — never library
  437. contents.
  438. - **Third-party sharing**: none. Nothing leaves your machine.
  439. - **Data retention**: the files and backups stay until you delete them; backups are
  440. capped at the five most recent per library.
  441. - **Contact**: <matejg03@gmail.com>, or a [GitHub issue](https://github.com/embedded-society/altium-designer-mcp/issues)
  442. for anything that need not be private.
  443. ---
  444. ## Documentation
  445. | For… | Read |
  446. |------|------|
  447. | Wiring the server into your AI client | [docs/CLIENT_SETUP.md](docs/CLIENT_SETUP.md) — one section per client |
  448. | What to ask for once it is connected | [docs/USAGE.md](docs/USAGE.md) — workflows, prompts, tips |
  449. | Telling the AI how to use it well | [docs/AGENT_GUIDE.md](docs/AGENT_GUIDE.md) (paste into a project brief), [docs/AI_WORKFLOW.md](docs/AI_WORKFLOW.md) |
  450. | Every tool, parameter and example | [docs/TOOLS.md](docs/TOOLS.md); error messages in [docs/errors.md](docs/errors.md) |
  451. | Why it is built this way | [docs/VISION.md](docs/VISION.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
  452. | The file formats, byte by byte | [docs/PCBLIB_FORMAT.md](docs/PCBLIB_FORMAT.md), [docs/SCHLIB_FORMAT.md](docs/SCHLIB_FORMAT.md) |
  453. | Security model and threat analysis | [docs/SECURITY.md](docs/SECURITY.md) (reporting: [SECURITY.md](SECURITY.md)) |
  454. | How releases are built and verified | [docs/RELEASING.md](docs/RELEASING.md); [code signing policy](docs/CODE_SIGNING_POLICY.md) |
  455. ---
  456. ## Contributing
  457. Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
  458. - Follow the style guide in [STYLE.md](STYLE.md)
  459. - Security issues: see [SECURITY.md](SECURITY.md)
  460. ---
  461. ## Development
  462. ```bash
  463. cargo test
  464. ```
  465. Write-path tests generate their own data programmatically; reader tests parse the committed
  466. Altium-authored golden fixtures (see [Sample Files](#sample-files)). Temporary files are
  467. created in `.tmp/` (git-ignored) and automatically cleaned up.
  468. The full build, formatting, and lint commands are canonical in
  469. [CONTRIBUTING.md § Development Setup](CONTRIBUTING.md#development-setup).
  470. ---
  471. ## Licence
  472. Copyright (C) 2026 The Embedded Society <https://github.com/embedded-society/altium-designer-mcp>.
  473. GNU General Public License v3.0 — see [LICENCE](LICENCE).
  474. ---
  475. ## Links
  476. - [MCP Specification](https://modelcontextprotocol.io/)
  477. - [Report an Issue](https://github.com/embedded-society/altium-designer-mcp/issues)
  478. ---
  479. ## Sample Files
  480. Altium-authored sample libraries are committed under `scripts/samples/` as **golden fixtures**:
  481. the reader tests (`tests/samples_pcblib.rs`, `tests/samples_schlib.rs`) parse them in CI as
  482. ground truth. The PowerShell/DelphiScript tooling that (re)generates them needs a real Altium
  483. installation and is manual-only.
  484. See [scripts/README.md](scripts/README.md) for details on the sample files and the on-site tooling.
  485. ---
  486. ## Prior Art & Acknowledgements
  487. This project stands on the shoulders of several excellent open-source efforts, and we're grateful
  488. for each:
  489. - **[AltiumSharp](https://github.com/issus/AltiumSharp)** (MIT) — the most complete open Altium
  490. reader/writer. Used as the authoritative reference (its DTOs, binary serialisation code, and golden
  491. `TestData`) for verifying our binary format against ground truth.
  492. - **[pyAltiumLib](https://github.com/ChrisHoyer/pyAltiumLib)** — an independent Python reader, used
  493. as our CI **readability oracle** (`tests/integration/`) to check that generated files actually
  494. parse.
  495. - **[python-altium](https://github.com/vadmium/python-altium)** — early Altium format
  496. documentation.
  497. - **[coffeenmusic/altium-mcp](https://github.com/coffeenmusic/altium-mcp)** (MIT) — an MCP server
  498. that drives the **live** Altium application. It's the complement to this project (we generate and
  499. edit library files *offline*; it controls a running session). We adapted its RunScript launch +
  500. file-based bridge pattern for our on-site Altium automation
  501. ([`scripts/altium/`](scripts/altium/)).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.