mcp-server-kicad

Let an AI assistant read, edit, and verify real KiCad projects.

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

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, where the installer does not add 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

Everything still on the old parser refuses a KiCad 10 file instead of silently downgrading it: the file is left untouched and the error names the format limit it hit. That covers the remaining board writers, the project server's hierarchy read tools, and your own symbol and footprint libraries. Migration progress is tracked in #9; the design behind it is written up in docs/adr-cst-substrate.md.

Windows and OneDrive

If your Documents folder is redirected to OneDrive, kicad-cli can die at startup with an access violation (exit 3221225477) because it cannot create its KiCad subfolder there. Every invocation fails, including kicad-cli --version. Point KiCad's own KICAD_DOCUMENTS_HOME at a directory that is not synced.

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