KiCad 工程自动化 MCP 服务

mcp-server-kicad

Let an AI assistant edit real KiCad projects without corrupting them.

109 MCP tools covering schematic capture, PCB layout, symbol and footprint libraries, ERC and DRC, and manufacturing exports. No screenshots, no copy-paste, no hand-edited s-expressions: the model calls tools, KiCad files change on disk.

Quick start • What you get • Configuration • Tool reference • Requirements • Contributing

[!IMPORTANT] Maintenance mode. As of October 2026 this project gets security fixes and KiCad compatibility fixes only. No new tools or features are planned. Existing installs keep working. Why

Why maintenance mode

The plugin was built on one idea: KiCad files are large, so an AI assistant should change them through tools instead of editing the text. We tested that idea against plain Claude Code with KiCad installed and no plugin: the same model (Claude Opus 5.5), the same settings and the same tasks, each result judged by KiCad 10 itself (netlist, board, ERC and DRC).

• Six single edits on a public KiCad 10 design (a value change, do-not-populate, a footprint swap, pads assigned to a net, a footprint rotation, a net renamed across sheets), three runs each. Plain Claude Code got all 18 right. With the plugin, 3 of 18 were right.
• A long session of 20 board edits. Both got every edit right, and the plugin's sessions used about 1.8 times as much context.
• Why the plugin failed, from reading every transcript:
  • It had no tool for some edits (a pad's net, the do-not-populate flag, swapping one footprint).
  • Its instructions told the model never to edit KiCad files directly, so the model stopped and asked instead.
  • Its board-sync tool rewrote almost every footprint on the board, so the model undid its own work.
• The premise did not hold in these tests. Plain Claude Code changed a 2 MB board without reading it whole: it searched for the part and edited only the lines it needed.

These were small tests on one design, not a verdict on every board or every model. They were enough to stop adding tools. The test material is not published, because the design it used carries no license.

What to use instead: a coding agent such as Claude Code, with KiCad installed. Ask it to check its changes with kicad-cli (netlist export, ERC, DRC) before it finishes.

Bug reports and fixes for KiCad compatibility are still welcome.

What it looks like

"Add a 100 nF decoupling cap on U1's VCC pin, then check ERC."

  get_pin_positions            locate U1's VCC and GND pins
  auto_place_decoupling_cap    place C3 and wire both pins to their nets
  run_erc                      report what the change broke

"Now push the netlist to the board and route it."

  update_pcb_from_schematic    sync footprints and pad nets onto the PCB
  autoroute_pcb                route with Freerouting
  run_drc                      clearance, width, and unconnected checks

Every tool works on the real file, and a write changes only the bytes you asked it to. An edit that cannot be done correctly is refused with the file intact. KiCad itself writes a design file in just two places: the library upgrades, and autoroute_pcb's routed copy, a new board that leaves yours untouched.

Quick start

Claude Code

Install the plugin. It wires up the server and ships the design skills with it:

claude plugin marketplace add ProductOfAmerica/mcp-server-kicad
claude plugin install kicad

Claude Desktop

Download kicad-<version>.mcpb from the latest release and install it from Settings, then Extensions. Claude Desktop fetches Python and the package itself; you need KiCad installed, plus Java 25 or newer for autoroute_pcb.

Desktop does not run from your project directory, so fill in the schematic, board, and export paths it asks for. Leave the kicad-cli field blank unless KiCad is installed somewhere unusual. The design skills are Claude Code only.

Everything else

pip install mcp-server-kicad

Then point your MCP client at the unified server, and name your schematic, board, and export folder in env by absolute path, so tools find them without being told on every call:

{
  "mcpServers": {
    "kicad": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad"],
      "env": {
        "KICAD_SCH_PATH": "/path/to/project/project.kicad_sch",
        "KICAD_PCB_PATH": "/path/to/project/project.kicad_pcb",
        "KICAD_OUTPUT_DIR": "/path/to/project"
      }
    }
  }
}

That single entry registers all 109 tools. A client that starts the server in your project's folder can leave env out: the server then takes the paths from the single .kicad_pro there (see How paths resolve). Prefer to split the tools across five smaller servers? See Configuration.

What you get

Five tool servers

Run them as one unified server, or separately when you want a smaller tool surface in context.

Six design skills (Claude Code plugin)

Tools alone let a model click every button. The bundled skills teach it which buttons, in what order, and what "done" looks like.

The design skills hand their artifacts to independent reviewer subagents (agents/) before moving on, so a bad BOM or a bad placement plan gets caught before it becomes a schematic.

Configuration

Split servers

Five entries instead of one, when you want to load only part of the tool surface:

{
  "mcpServers": {
    "kicad-schematic": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-schematic"]
    },
    "kicad-pcb": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-pcb"]
    },
    "kicad-symbol": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-symbol"]
    },
    "kicad-footprint": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-footprint"]
    },
    "kicad-project": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-project"]
    }
  }
}

uvx --from mcp-server-kicad mcp-server-kicad-schematic

How paths resolve

Highest priority wins:

1. Tool parameters. Every tool accepts an explicit path.
2. Environment variables. They override anything auto-detected.
3. Auto-detect. The working directory is scanned for a .kicad_pro, and the schematic, board, and library paths are derived from it.

Requirements

• Python 3.11+

• KiCad 9.x or 10.x, only for the tools that call KiCad:

  • kicad-cli: ERC, DRC, exports, jobsets, get_version, the library upgrades and update_pcb_from_schematic
  • pcbnew Python bindings: fill_zones and autoroute_pcb (which also needs Java 25 or newer; see The Freerouting download)
  • KiCad's stock libraries: placing a stock symbol or footprint

  Every other tool parses files directly and needs no KiCad.

CI covers Linux (KiCad 9 and 10), macOS and Windows (KiCad 10), and Python 3.11 to 3.14.

The Freerouting download

autoroute_pcb runs Freerouting. Unless FREEROUTING_JAR names a jar, its first call downloads Freerouting 2.5.0, freerouting-2.5.0.jar (65 MB, needs Java 25 or newer), from https://github.com/freerouting/freerouting/releases/download/v2.5.0/freerouting-2.5.0.jar and caches it as ~/.local/share/mcp-server-kicad/freerouting-2.5.0.jar (%USERPROFILE%\.local\share\mcp-server-kicad\ on Windows). Its SHA-256 is checked against the value pinned in this package before the download is saved and every time the cached copy is used. A download that does not match is not saved; a cached copy that does not match is not run, and is downloaded again.

Freerouting is run with --gui.enabled=false and --usage_and_diagnostic_data.disable_analytics=true, the settings its documentation gives for running headless and for not sending usage data, so it opens no window and its analytics stay off. When it starts, Freerouting still asks GitHub for its newest release; it has no setting to turn that off.

To skip the download, set FREEROUTING_JAR to the absolute path of a Freerouting jar you trust. That jar is used as given, with no hash check. A relative path, or one that names no file, is ignored and the download goes ahead. Earlier releases cached an unpinned freerouting.jar in the same folder; it is no longer read and can be deleted.

Finding your KiCad install

A stock install needs no configuration. kicad-cli is found on PATH, then in /Applications/KiCad/KiCad.app on macOS, then under Program Files and AppData on Windows, newest first. The stock libraries and pcbnew's Python are found relative to it. For an unusual install:

Without kicad-cli, the tools that need it stay listed and fail with a message naming KICAD_CLI_PATH.

KiCad 10 files

The server's own reads and writes handle KiCad 9 and 10 schematics, boards, symbol libraries and footprints alike, and never change bytes you did not ask to change (see docs/adr-cst-substrate.md). Work handed to KiCad itself only succeeds if your install can load the file, and KiCad 9 cannot load a KiCad 10 board:

• fill_zones and autoroute_pcb refuse a KiCad 10 board on a KiCad 9 pcbnew before starting; install KiCad 10 or point KICAD_PYTHON at one. autoroute_pcb on a KiCad 9 board through KiCad 10's pcbnew works but warns that the routed copy comes back in KiCad 10 format. It never touches the original board.
• upgrade_symbol_lib and upgrade_footprint_lib let KiCad rewrite your files, by design. Each file is replaced atomically and only if it changed, so an interrupted upgrade leaves none damaged. A backup goes to <name>.bak, overwritten every run.

Windows: Controlled Folder Access

Defender's Controlled Folder Access blocks unrecognised apps from writing under Documents, where KiCad keeps its data. kicad-cli then crashes at startup (exit 3221225477) on every call, --version included, and the error looks like a missing file: error 2: The system cannot find the file specified.

The server works around this: it retries once with KICAD_DOCUMENTS_HOME pointed at an unprotected local folder and keeps it for the session. Set KICAD_DOCUMENTS_HOME yourself to pick the folder (this turns the retry off).

It cannot fix your project files. If your project lives under Documents, the write tools fail the same way. Move the project, or allow the tools under Windows Security > Virus & threat protection > Ransomware protection > Allow an app through Controlled folder access.

Tool reference

Debugging

Drive the servers by hand with the MCP Inspector:

npx -y @modelcontextprotocol/inspector uvx --from mcp-server-kicad mcp-server-kicad

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for development setup, and docs/adr-cst-substrate.md for the architecture decisions behind the byte-preserving write path.

• Report a bug
• Browse open issues
• Security policy
• Code of conduct

License

GPL-3.0-or-later. Releases up to and including 0.20.1 were MIT-licensed; see NOTICE.