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

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, wire it, drop the junctions
  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. Writes go through a byte-preserving substrate, so bytes you did not ask to change reach the disk unchanged, and an edit that cannot be done correctly is refused with the file intact. That now covers every board and schematic this server writes. The two library upgrades are the only tools that let KiCad do the writing, and they say so on themselves.

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, so KiCad is the only thing you need installed first.

Fill in the schematic, board, and export paths it asks for. Unlike the Claude Code plugin, Desktop does not run from your project directory, so nothing is auto-detected. Leave the kicad-cli field blank unless KiCad lives somewhere unusual; stock installs are found on their own, on every platform. The design skills are Claude Code only.

Everything else

pip install mcp-server-kicad

Then point your MCP client at the unified server and set cwd to a KiCad project directory so paths resolve themselves:

{
  "mcpServers": {
    "kicad": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad"],
      "cwd": "/path/to/your/kicad/project"
    }
  }
}

That single entry registers all 109 tools. Prefer to split them 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"],
      "cwd": "/path/to/your/kicad/project"
    },
    "kicad-pcb": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-pcb"],
      "cwd": "/path/to/your/kicad/project"
    },
    "kicad-symbol": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-symbol"],
      "cwd": "/path/to/your/kicad/project"
    },
    "kicad-footprint": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-footprint"],
      "cwd": "/path/to/your/kicad/project"
    },
    "kicad-project": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-project"],
      "cwd": "/path/to/your/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.10+
• KiCad 9.x or 10.x, for the tools that shell out to kicad-cli: ERC, DRC, and every export. The read and write tools parse files directly and need no KiCad install at all.

CI runs the full suite on Linux against KiCad 9 and on macOS against KiCad 10, plus a KiCad-free matrix across Python 3.10 through 3.13.

Finding your KiCad install

kicad-cli is looked up on PATH, then inside /Applications/KiCad/KiCad.app on macOS, then in the standard Windows install folders, machine-wide under Program Files and per-user under AppData, newest version first. Neither installer adds it to PATH. Everything else in the KiCad tree is located relative to it, the same way KiCad itself does it, so a stock install on any platform needs no configuration: the stock symbol libraries and the bundled Python that provides pcbnew are both found automatically.

Override any of it if your install is unusual:

CLI-backed tools are always registered. Without kicad-cli they fail with a message naming KICAD_CLI_PATH, rather than vanishing from the tool list.

KiCad 10 files

Every tool parses and edits through the byte-preserving substrate, so none of them refuses a file on its format version, and none of them rewrites bytes you did not ask to change. Two caveats are worth knowing about.

autoroute_pcb needs a pcbnew whose era matches the board, because it uses one for the DSN export and the SES import. It checks before it starts. A KiCad 10 board on a KiCad 9 pcbnew is refused with a message naming both versions; install KiCad 10 or point KICAD_PYTHON at one. The other direction runs and warns, because the routed copy comes back in the KiCad 10 format. Your original board is untouched either way, since this one writes a copy.

upgrade_symbol_lib and upgrade_footprint_lib are the one place KiCad still rewrites your file, because changing the format is exactly what you asked for. It rewrites a copy: the result is moved into place atomically, so a library can never be left half-written, and only files whose content actually changed are touched. Each file is atomic; the library as a whole is not a transaction, so an interrupted upgrade leaves some footprints migrated and none damaged. A backup is still taken at <name>.bak, overwritten every run, because that is the undo for an upgrade that worked.

fill_zones and update_pcb_from_schematic used to be listed here and no longer are. fill_zones still asks pcbnew to compute the fills, because nothing else can, but pcbnew only reads: the copper comes back as coordinates and the substrate splices it in. update_pcb_from_schematic no longer uses pcbnew at all. Both leave everything they were not asked to change byte-identical, including the format stamp. The design behind the substrate is written up in docs/adr-cst-substrate.md.

Windows: Controlled Folder Access

Windows Defender's ransomware protection, Controlled Folder Access, guards your Documents folder and blocks writes from applications it does not recognise. KiCad keeps its own data there, a 3D cache and templates under Documents\KiCad, so a blocked write kills kicad-cli at startup with an access violation (exit 3221225477) before it does any work. Every invocation fails, --version included.

The block surfaces as error 2: The system cannot find the file specified, which is why this reads like a missing folder rather than a permission problem. Measured on a machine with the feature on: the folder is plainly there and a write into it still fails with FileNotFoundError.

kicad-cli is handled for you. On that crash the server retries once with KiCad's own KICAD_DOCUMENTS_HOME pointed at a local folder outside the protected set, then reuses it for the session. Nothing to configure, and a machine without the block never sees any of it. Setting KICAD_DOCUMENTS_HOME yourself picks the folder and disables the retry, on the grounds that a directory you chose is yours to fix.

Your project files are a separate matter. The same block applies to any write, so if your KiCad project lives under Documents, the write tools can fail the same confusing way, and the server cannot repair that: it is the location you asked it to edit. Either keep projects outside the protected folders, or allow the tools through at 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 @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

License

MIT