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.

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. One caveat, and it is not about the file format: autoroute_pcb hands the board to pcbnew for the DSN export and the SES import, so it additionally needs a pcbnew whose era matches the board. It checks that before it starts. A KiCad 10 board on a KiCad 9 pcbnew is refused with a message naming both versions, rather than failing somewhere inside the export; install KiCad 10 or point KICAD_PYTHON at one. The other direction runs, and the result carries a warning: a KiCad 9 board routed through a KiCad 10 pcbnew comes back as a routed copy in the KiCad 10 format, because that is what pcbnew saves. Your original board is untouched either way. 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