altium-designer-mcp

altium-designer-mcp is an MCP (Model Context Protocol) server for AI-assisted management of Altium Designer component libraries. It gives AI assistants (such as Claude Code, Claude Desktop, Cursor, Antigravity, VS Code Copilot, and any other MCP client) file I/O and primitive placement tools for .PcbLib (footprint) and .SchLib (symbol) library files, enabling them to create and maintain arbitrary components, not just pre-programmed footprint types. The core idea of the tool is: the AI handles engineering intelligence (datasheet → dimensions → style), and the tool handles file I/O. This is because Altium's binary .PcbLib / .SchLib files use an undocumented OLE compound format, are prone to corruption, and Altium will silently refuse to open malformed files, so the AI cannot write to them directly. Who it is for: anyone who builds or maintains Altium component libraries and uses an MCP-capable AI assistant. Client configuration has been verified on stdio MCP clients including 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 others, with support for Windows, Linux, and macOS. The server provides 34 tools and works with both .PcbLib and .SchLib. Tools by category include: inspection and visualization, component management, library operations, backup and safety. Full parameters and examples are in docs/TOOLS.md. Footprint primitives (PcbLib): the shape property on pads controls the copper shape, which can be used to mark pin 1, following IPC-7351 conventions (rectangular or square corners for pin 1, rounded corners for other pads). Symbol primitives (SchLib): supports standard Altium layers such as Top Overlay, Mechanical 13, etc.; layer names can use Altium spelling or camel case, and capitalization is notcase-sensitive, and every tool accepts the same spelling. Prebuilt binaries (Linux x86_64, macOS aarch64, Windows x86_64) are available on the Releases page, and each archive contains an installation README and docs/CLIENT_SETUP.md covering all known MCP clients. The Linux binary requires glibc 2.34 or newer (Ubuntu 22.04, Debian 12, RHEL 9 and later). Claude Desktop users do not need the archive: they can install the one-click extension altium-designer-mcp.mcpb (altium-designer-mcp.dxt in older versions) from the same page, via Settings → Extensions → Advanced settings → Install Extension. Code signing policy: Windows binaries will be signed through the SignPath Foundation; until approval they are unsigned, and each release includes a signed build provenance attestation. Using in a container: the repository's Dockerfile produces the same --locked release build as the released binaries. The mounted /libraries folder is the container's entire allowlist. Client configuration is "command": "docker" and "args": ["run", "-i", "--rm", "-v", "/path/to/libraries:/libraries", "altium-designer-mcp"]. Building from source: see CONTRIBUTING.md; the optimized binary comes from cargo build --release and is located at target/release/altium-designer-mcp. Verifying a downloaded release: release archives are built by GitHub Actions with a signed SLSA build provenance attestation that can be traced back to the workflow run and commit. The binaries are not code-signed, so Windows SmartScreen and macOS Gatekeeper will warn on first run (on macOS, right-click → Open). The attestation is a stronger check. Command-line usage: every MCP client needs the same two absolute paths——Binaries and configuration files — only the write locations differ. Use absolute paths; the client does not search PATH or expand ~. The server reads one JSON file, or none: altium-designer-mcp --allow <DIR> grants folders on the command line and runs everything else by default, which is how the Claude Desktop extension starts it. Configuration location: ~/.altium-designer-mcp/config.json on Linux/macOS, %USERPROFILE%.altium-designer-mcp\config.json on Windows. STEP model integration: STEP models are attached, not generated. The tool links existing STEP files to footprints. Altium supports two ways of referencing 3D models: embedded and external. When copying or merging components: embedded models move with the component — copy_component_cross_library and merge_libraries both stream the referenced models to the target (models shared by multiple footprints are copied only once), so the bodies still resolve after the move. External model references: copy_component_cross_library removes them by default and warns, because paths relative to the source library rarely resolve elsewhere — pass preserve_external_paths=true to keep them. merge_libraries preserves them as-is. Embedding models in the source library is the reliable way to preserve 3D data in any copy. Extracting embedded models: use extract_step_model to extract embedded STEP data from a library. Parametric 3D model generation is planned as a future project, using a dedicated mechanical MCP server. Automatic backups: before any destructive operation (delete, update, merge, batch update), the server automatically creates a timestamped backup of the target file. Backup format: the most recent 5 backups of each file are kept, and older ones are automatically removed. Operations that create backups include: delete_component, update_component, update_primitive, rename_component, copy_component_cross_library (target file), merge_libraries (target file), reorder_components, manage_schlib_parameters, manage_schlib_footprints, write_pcblib / write_schlib (when overwriting), import_library (when overwriting), restore_backup (before the current file is replaced by the selected backup). Managing backups: use list_backups to view available backups, and restore_backup to restore a previous version. Dry-run support: these operations support dry_run=true to preview changes without modifying files. Libraries on non-Western Windows: Altium stores most names as raw bytes in the Windows code page of the machine that wrote them, with no record. Libraries written on Chinese, Japanese, Korean, Central European, Cyrillic, Greek, Turkish, Baltic, Hebrew, Arabic, Vietnamese, or Thai Windows will appear as mojibake in tools that assume Windows-1252 (such as £¨0402 instead of (0402). This server infers the library's code page from footprints whose real names are recorded twice (once as bytes, once as Unicode), reads each name through it, and writes it back as-is, with rewrites preserving identical bytes. No configuration is needed to read or edit such libraries. Two cases are worth knowing: 1. Names that Altium must display. Altium Designer 21 and earlier display footprint names from these bytes, decoded through the code page of the machine running it, and never read the Unicode copy. Therefore new or renamed footprints are written in the server's own code page—the system code page on Windows. When the machine the server runs on has a different locale from the Altium that opens the library, specify that page in the configuration file with ansi_code_page or on the command line with --ansi-code-page (874, 932, 936, 949, 950, 1250 to 1258, or 65001). 2. Characters the page cannot hold. Altium writes ? instead, and this server does the same; the full name is still retained in the component parameters, as Altium retains it, and is returned in full the next time it is read. Long component names: component names longer than 31 characters are supported. The OLE compound file format limits stored names to 31 characters, so longer names are automatically truncated internally, and the full name is retained in the component parameters. This is handled transparently, preserving component names of any length across read and write round trips. Data collection:None. The server has no telemetry or analytics and never contacts any service, including this project. When using --http it listens for MCP clients on the given address and still sends nothing. Use and storage: it only reads and writes library files within the granted folders (allowed_paths or --allow), and creates timestamped .bak copies alongside them before changes. The optional audit log (logging.audit_log_path) is a local file of your choosing that keeps tool names, file names and results — it never keeps library contents. Third-party sharing: none. Data retention: files and backups are kept until you delete them; at most the 5 most recent backups are kept per library. Contact: matejg03@gmail.com, or a GitHub issue. Contributions are welcome, see CONTRIBUTING.md. Follow the STYLE.md style guide. For security issues see SECURITY.md. Write-path tests generate their own data programmatically; read tests parse committed Altium-authored golden fixtures. Temporary files are created in .tmp/ (git-ignored) and cleaned up automatically. Full build, format and lint commands are in CONTRIBUTING.md. Copyright (C) 2026 The Embedded Society. GNU General Public License v3.0, see LICENCE. MCP specification. Altium-authored sample libraries are committed as golden fixtures under scripts/samples/: read tests (tests/samples_pcblib.rs, tests/samples_schlib.rs) parse them in CI as ground truth. The PowerShell/DelphiScript tooling to regenerate them requires a real Altium installation and is manual only. See scripts/README.md. Prior art and acknowledgements: AltiumSharp (MIT) — the most complete open-source Altium reader/writer, used as the authoritative reference (its DTOs, binary serialization code and golden TestData) to validate the binary format. pyAltiumLib — an independent Python reader, used as a CI readability oracle to check that generated files actually parse. python-altium — early Altium format documentation. coffeenmusic/altium-mcp (MIT) — an MCP server that drives a live Altium application, complementary to this project (we generate and edit library files offline; it controls a running session). We adapted its RunScript launch + file-based bridge pattern for live Altium automation (scripts/altium/).