mcp-server-kicad

Purpose

mcp-server-kicad lets an AI assistant edit real KiCad projects without damaging files, covering schematic capture, PCB layout, symbol and footprint libraries, ERC/DRC, and manufacturing export. The model modifies KiCad files directly on disk by calling tools, with no screenshots, copy-paste, or manual editing of s-expressions.

Main Capabilities

Provides 109 MCP tools, covering schematic drawing, PCB layout, symbol and footprint library operations, ERC and DRC, manufacturing file export (Gerber, BOM, 3D models), and more. Every tool acts on real files, and writes go through a byte-preserving layer, ensuring that bytes for unrequested changes reach disk exactly as they were; edits that cannot be completed correctly are rejected, and files remain intact. This mechanism covers all of this server's edits to boards or schematics. KiCad itself writes design files in only two places: library upgrades (which announce themselves) and the routing copy of autoroute_pcb (a new board saved by pcbnew, with the original board unaffected).

Usage

Install the Plugin (Claude Desktop)

Download kicad-<version>.mcpb from the latest release, install it in Settings, then open Extensions. Claude Desktop fetches Python and the package itself, so you only need to install KiCad first. Fill in the schematic, board, and export paths it requests. Unlike the Claude Code plugin, Desktop does not run from the project directory, so it does not auto-detect. Leave the kicad-cli field blank unless KiCad is installed in a special location; standard installations are found automatically on every platform. Design skills are limited to Claude Code.

Unified Server

Point the MCP client at the unified server and set cwd to the KiCad project directory so paths resolve automatically. This single entry registers all 109 tools. If you want to split the tools across five smaller servers, see Configuration.

Five Tool Servers

Can be run as a unified server, or separately, to use a smaller tool surface in context.

Six Design Skills (Claude Code Plugin)

With only the tools, the model can press each button; the bundled skills teach it which buttons to press, in what order,and what "done" looks like. Design skills hand their artifacts to an independent review subagent (agents/) before continuing, so a bad BOM or layout plan is caught before it becomes a schematic.

Path resolution

Priority from high to low:

1. Tool arguments: every tool accepts an explicit path.
2. Environment variables: override any auto-detection result.
3. Auto-detection: scan the working directory for .kicad_pro, and derive the schematic, board, and library paths from it.

Manual run

The server can be driven manually using MCP Inspector. Each server can also be run directly.

Runtime requirements

Requires KiCad 9.x or 10.x (for tools that hand work to KiCad). ERC, DRC, all exports, jobset, get_version, library upgrades, and update_pcb_from_schematic all run kicad-cli; fill_zones and autoroute_pcb require KiCad's pcbnew Python bindings, and autoroute_pcb also requires Java. Placing parts from KiCad's bundled symbol or footprint libraries requires these libraries, which ship with KiCad. All other read/write tools parse files directly and do not require KiCad to be installed.

CI runs the full suite on Linux against KiCad 9 and KiCad 10, on macOS and Windows against KiCad 10, plus a no-KiCad matrix covering Python 3.10 through 3.14.

Finding a KiCad installation

kicad-cli is first looked up in PATH, then in /Applications/KiCad/KiCad.app on macOS, then in the standard Windows installation folders (machine-level under Program Files and user-level under AppData, with the newest version taking priority). Neither installer adds it to PATH. Other contents in the KiCad directory are located relatively in the same way, so a standard installation on any platform requires no configuration: the bundled symbol libraries and the bundled Python that provides pcbnew are both found automatically.

Any setting can be overridden to accommodate a special installation. CLI-backed tools are always registered; without kicad-cli they will failand gives a message indicating KICAD_CLI_PATH, rather than disappearing from the tool list.

Format version

Every tool parses and edits through a byte-preserving underlying layer, so the server's own reads and writes will not reject a file due to format version, nor will they rewrite bytes for unrequested changes. What the tools hand to KiCad itself via kicad-cli or pcbnew only works if your installation can load that file; a KiCad 9 installation cannot load a KiCad 10 board.

autoroute_pcb and fill_zones both need a pcbnew that can load the board: autoroute for DSN export and SES import, fill_zones for computing fills. Both check before starting. KiCad 9's pcbnew will reject a KiCad 10 board and give a message indicating both versions; install KiCad 10 or point KICAD_PYTHON at it. In the opposite direction, autoroute_pcb will run and warn, because the routed copy is returned in KiCad 10 format. In any case, autoroute will not modify the original board, because it writes to a copy.

upgrade_symbol_lib and upgrade_footprint_lib are the only places where KiCad will still rewrite files, because changing the format is exactly what you asked for. It rewrites a copy: the result is moved into place atomically, so the library is never left half-written, and only files whose contents actually changed are touched. Each file is atomic; the library as a whole is not a transaction, so an interrupted upgrade will leave some footprints migrated, but not corrupted. A <name>.bak backup is still generated, overwritten on each run, as a means of undoing a successful upgrade.

fill_zones and update_pcb_from_schematic were also listed here for having pcbnew rewrite the board, but that is no longer the case. fill_zones still asks pcbnew to compute fills, because there is no other way to do it, but pcbnew only reads: the copper pours are returned as coordinates and spliced in by the underlying layer. update_pcb_from_schematic no longer uses pcbnew. Both leave content for unrequested changes byte-identical, including the format stamp.

Limitations and caveats

Windows: Controlled folder access

WiWindows Defender's ransomware protection (Controlled Folder Access) protects the Documents folder and blocks writes from unrecognized apps. KiCad puts its own data there (3D cache and templates under Documents\KiCad), so blocked writes cause an access violation at kicad-cli startup (exit code 3221225477), failing before any work begins. Every invocation fails, including --version.

The block manifests as error 2: the system cannot find the specified file, so it looks like a missing folder rather than a permissions issue. Measured on a machine with the feature enabled: the folder clearly exists, yet writes still fail with FileNotFoundError.

kicad-cli already handles this for you: when that crash occurs, the server retries once, pointing KiCad's own KICAD_DOCUMENTS_HOME to a local folder outside the protected set, then reuses it for the entire session. No configuration needed; machines without the block won't see any of this. Setting KICAD_DOCUMENTS_HOME yourself selects the folder and disables the retry.

Project files are another matter. The same block applies to any write, so if a KiCad project is under Documents, write tools may fail in the same confusing way, and the server cannot fix it: that's the location you asked it to edit. Put projects outside the protected folder, or allow these tools in Windows Security, Virus & threat protection, Ransomware protection, Allow an app through Controlled folder access.

Other known limitations

• A KiCad 9 installation cannot load KiCad 10 boards (this limitation applies when the tool hands off to KiCad itself).
• CLI-backed tools fail without kicad-cli, but do not disappear from the tool list.
• Library upgrades are not a single transaction; an interruption leaves some footprints already migrated (but not corrupted).
• Standard installations need no configuration; special installations can override paths via environment variables.

Summary

This project suits engineers who want to automate the KiCad design workflow with an AI assistant, providing a complete toolchain from schematic to manufacturing export, and safeguarding files through a byte-preserving write mechanism. Issues and pull requests are welcome; see CONTRIBUTING.md for development setup, and docs/adr-cst-substrat for the architectural decision on the byte-preserving write path.e.md。