# 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. [![PyPI](https://img.shields.io/pypi/v/mcp-server-kicad?style=flat-square&logo=pypi&logoColor=white&label=pypi)](https://pypi.org/project/mcp-server-kicad/) [![Python](https://img.shields.io/pypi/pyversions/mcp-server-kicad?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/mcp-server-kicad/) [![KiCad](https://img.shields.io/badge/KiCad-9%20%7C%2010-314CB0?style=flat-square&logo=kicad&logoColor=white)](https://www.kicad.org/) [![Tests](https://img.shields.io/github/actions/workflow/status/ProductOfAmerica/mcp-server-kicad/ci.yml?branch=main&style=flat-square&logo=githubactions&logoColor=white&label=tests)](https://github.com/ProductOfAmerica/mcp-server-kicad/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE) [Quick start](#quick-start) • [What you get](#what-you-get) • [Configuration](#configuration) • [Tool reference](#tool-reference) • [Requirements](#requirements) • [Contributing](#contributing)

--- ## What it looks like ```text "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. 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 edit this server makes to a board or schematic. KiCad itself writes a design file in only two places: the library upgrades, which say so on themselves, and `autoroute_pcb`'s routed copy, a new board that `pcbnew` saves while yours stays untouched. ## Quick start ### Claude Code Install the plugin. It wires up the server and ships the design skills with it: ```bash claude plugin marketplace add ProductOfAmerica/mcp-server-kicad claude plugin install kicad ``` ### Claude Desktop Download `kicad-.mcpb` from the [latest release][latest] 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. [latest]: https://github.com/ProductOfAmerica/mcp-server-kicad/releases/latest ### Everything else ```bash 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: ```json { "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](#configuration). ## What you get ### Five tool servers Run them as one unified server, or separately when you want a smaller tool surface in context. | Server | Tools | What it does | |--------|:-----:|--------------| | `mcp-server-kicad-schematic` | 42 | Schematic read/write, net tracing, ERC, exports (PDF, SVG, DXF, netlist, BOM) | | `mcp-server-kicad-pcb` | 34 | Board read/write, netlist import, zones, DRC, autorouting, exports (Gerber, drill, 3D, pick-and-place) | | `mcp-server-kicad-project` | 24 | Project scaffolding, hierarchical sheets, hierarchy validation, annotation, cross-sheet net tracing | | `mcp-server-kicad-symbol` | 5 | Symbol library browsing, authoring, SVG export, format upgrade | | `mcp-server-kicad-footprint` | 4 | Footprint library browsing, SVG export, format upgrade | ### 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. | Skill | Kicks in when | |-------|---------------| | [`using-kicad`](skills/using-kicad/SKILL.md) | Any electronics or EDA conversation starts. Routes to the right skill below | | [`circuit-design`](skills/circuit-design/SKILL.md) | Choosing topology, regulators, and component values, before any file exists | | [`schematic-plan`](skills/schematic-plan/SKILL.md) | Planning exact placement coordinates and wiring. Pure planning, no writes | | [`schematic-design`](skills/schematic-design/SKILL.md) | Executing that plan, or modifying an existing schematic | | [`pcb-layout`](skills/pcb-layout/SKILL.md) | Placing footprints, routing, zones, stackup, trace widths | | [`verification`](skills/verification/SKILL.md) | ERC and DRC failures, unconnected nets, export prep | The design skills hand their artifacts to independent reviewer subagents ([`agents/`](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:

Five-server MCP config

```json { "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" } } } ``` Each is also runnable directly: ```bash 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. | Variable | Points at | |----------|-----------| | `KICAD_SCH_PATH` | a `.kicad_sch` schematic file | | `KICAD_PCB_PATH` | a `.kicad_pcb` board file | | `KICAD_SYM_LIB` | a `.kicad_sym` symbol library file | | `KICAD_FP_LIB` | a `.pretty` footprint library directory | | `KICAD_OUTPUT_DIR` | where exports and reports are written | ## Requirements - **Python 3.10+** - **KiCad 9.x or 10.x**, for the tools that hand work to KiCad. ERC, DRC, every export, jobsets, `get_version`, the library upgrades and `update_pcb_from_schematic` run `kicad-cli`; `fill_zones` and `autoroute_pcb` need KiCad's `pcbnew` Python bindings, and `autoroute_pcb` needs Java too. Placing a part from KiCad's stock symbol or footprint libraries needs those libraries, which come with KiCad. Every other read and write tool parses files directly and needs no KiCad install. CI runs the full suite on Linux against KiCad 9 and on macOS and Windows against KiCad 10, plus a KiCad-free matrix across Python 3.10 through 3.14. ### 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: | Variable | Overrides | |----------|-----------| | `KICAD_CLI_PATH` | the `kicad-cli` executable, and everything derived from its location | | `KICAD_SYMBOL_DIR` | the directory holding the stock `.kicad_sym` libraries | | `KICAD_PYTHON` | the interpreter used for `pcbnew` (`fill_zones`, `autoroute_pcb`), as an absolute path or a name found on `PATH` | 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 | File | What works today | |------|------------------| | `.kicad_sch` | Everything, read and write: the whole schematic server and the whole project server | | `.kicad_pcb` | Everything, read and write | | `.kicad_sym`, `.kicad_mod` | Everything: your own libraries as well as the stock ones | Every tool parses and edits through the byte-preserving substrate, so the server's own reads and writes refuse no file on its format version, and none of them rewrites bytes you did not ask to change. What a tool hands to KiCad itself, through `kicad-cli` or `pcbnew`, only works if your install can load the file, and a KiCad 9 install cannot load a KiCad 10 board. Two caveats are worth knowing about. `autoroute_pcb` and `fill_zones` both need a `pcbnew` that can load the board: autoroute uses one for the DSN export and the SES import, and `fill_zones` uses one to compute the fills. Both check before they start. 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. In the other direction `autoroute_pcb` runs and warns, because the routed copy comes back in the KiCad 10 format. Your original board is untouched by autoroute either way, since it 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 `.bak`, overwritten every run, because that is the undo for an upgrade that worked. `fill_zones` and `update_pcb_from_schematic` also used to be listed here for letting `pcbnew` rewrite your board, and no longer do. `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](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

Schematic (42 tools)

**Read** | Tool | Description | |------|-------------| | `get_schematic_summary` | Get item counts for a schematic sheet | | `list_schematic_components` | List all components (symbols) on a sheet | | `list_schematic_labels` | List all net labels on a sheet | | `list_schematic_wires` | List all wires on a sheet | | `list_schematic_global_labels` | List all global labels on a sheet | | `list_schematic_hierarchical_labels` | List all hierarchical labels on a sheet | | `list_schematic_sheets` | List all hierarchical sheet blocks on a sheet | | `list_schematic_junctions` | List all junctions on a sheet | | `list_schematic_no_connects` | List all no-connect flags on a sheet | | `list_schematic_bus_entries` | List all bus entries on a sheet | | `get_symbol_pins` | Get pin info for a symbol in the schematic's `lib_symbols` | | `get_pin_positions` | Get absolute pin positions for a placed component, accounting for rotation and mirror | | `get_net_connections` | Get all connections for a named net (multi-hop BFS wire tracing) | | `list_unconnected_pins` | List unconnected pins from ERC data | **Write** | Tool | Description | |------|-------------| | `place_component` | Place a component in the schematic | | `remove_component` | Remove a component by reference designator | | `move_component` | Move a placed component to a new position | | `set_component_property` | Set any property (Value, Reference, Footprint, ...) on a placed component | | `add_lib_symbol` | Load a symbol definition from a `.kicad_sym` library into the schematic | | `add_wires` | Add one or more wires between points, auto-creating junctions on T-connections | | `remove_wire` | Remove a wire segment | | `add_junctions` | Add one or more junction dots | | `remove_junction` | Remove a junction dot | | `add_label` | Add a net label at a position | | `remove_label` | Remove a net label or global label | | `add_global_label` | Add a global net label visible across all sheets | | `add_hierarchical_label` | Add a hierarchical label for sheet-to-sheet connections | | `remove_hierarchical_label` | Remove a hierarchical label by name or UUID | | `modify_hierarchical_label` | Modify text, shape, or position of a hierarchical label | | `add_power_symbol` | Place a power symbol (VCC, GND, +3V3, PWR_FLAG, ...) | | `add_text` | Add a text annotation to the schematic | | `remove_text` | Remove text annotation(s) by content, optionally filtered by position | | `wire_pins_to_net` | Wire one or more pins to a named net | | `connect_pins` | Wire two component pins together | | `auto_place_decoupling_cap` | Automatically place a decoupling capacitor near an IC | | `no_connect_pin` | Place a no-connect flag on an unused pin (idempotent) | | `remove_no_connect` | Remove no-connect flag(s) from a pin | | `set_page_size` | Set the schematic page size | **Analysis and export** | Tool | Description | |------|-------------| | `run_erc` | Run Electrical Rules Check, with `project_path` support for hierarchies | | `export_schematic` | Export schematic to PDF, SVG, or DXF | | `export_netlist` | Export the schematic netlist | | `export_bom` | Export a Bill of Materials as CSV |

PCB (34 tools)

**Read** | Tool | Description | |------|-------------| | `list_pcb_footprints` | List all footprints on the board | | `list_pcb_traces` | List all traces on the board | | `list_pcb_nets` | List all nets on the board | | `list_pcb_zones` | List all zones on the board | | `list_pcb_layers` | List all layers on the board | | `list_pcb_graphic_items` | List all graphic items on the board | | `get_board_info` | Board summary: footprint count, trace count, net count, thickness | | `get_footprint_pads` | Get pad info for a placed footprint | | `get_footprint_bounds` | Get the board-coordinate bounding box of a placed footprint | **Write** | Tool | Description | |------|-------------| | `place_footprint` | Place a footprint on the board | | `move_footprint` | Move a footprint to a new position | | `remove_footprint` | Remove a footprint by reference designator | | `add_trace` | Add a trace segment between two points | | `remove_traces` | Remove trace segments matching filters | | `set_trace_width` | Change the width of existing traces | | `remove_dangling_tracks` | Detect and remove trace segments with unconnected endpoints | | `add_via` | Add a via at a position | | `add_thermal_vias` | Add a grid of thermal vias under a footprint pad | | `add_pcb_text` | Add text to the board (silkscreen, fab layer, ...) | | `add_pcb_line` | Add a graphic line (edge cuts, silkscreen, ...) | | `add_copper_zone` | Create an unfilled copper zone | | `add_keepout_zone` | Create a keep-out zone restricting tracks, vias, pads, pours, or footprints | | `fill_zones` | Fill all copper zones on the board | | `set_net_class` | Create or update a net class with design rules | | `update_pcb_from_schematic` | Import or sync the schematic netlist onto the board: footprints, their fields and footprint filters, DNP and BOM flags (position-file flag too on KiCad 10), sheet linkage and pad nets; libraries through the project's and the user's `fp-lib-table` | **Analysis and export** | Tool | Description | |------|-------------| | `run_drc` | Run Design Rules Check on the board | | `check_placement` | Check whether a proposed footprint position hits a keep-out zone or the board edge | | `validate_board` | Check every placed footprint against keep-out zones and the board edge | | `autoroute_pcb` | Autoroute traces using the Freerouting autorouter | | `export_pcb` | Export board layers to PDF, SVG, or DXF | | `export_gerbers` | Export Gerber files, all layers or a specific list | | `export_3d` | Export a 3D model (STEP/STL/GLB) or render the 3D view to PNG | | `export_positions` | Export a component position file for pick and place | | `export_ipc2581` | Export in IPC-2581 format for manufacturing data exchange |

Project (24 tools)

**Scaffolding** | Tool | Description | |------|-------------| | `create_project` | Create a KiCad 9 project (`.kicad_pro`, `.kicad_prl`, `.kicad_sch`) | | `create_schematic` | Create a blank schematic file | | `create_symbol_library` | Create a blank symbol library file | | `create_sym_lib_table` | Create a `sym-lib-table` file | **Sheet management** | Tool | Description | |------|-------------| | `add_hierarchical_sheet` | Add a hierarchical sheet with matching labels in the child | | `remove_hierarchical_sheet` | Remove a hierarchical sheet block from a parent | | `modify_hierarchical_sheet` | Modify sheet name, file, width, or height | | `move_hierarchical_sheet` | Move a sheet block to a new position, pins included | | `add_sheet_pin` | Add a pin to an existing hierarchical sheet block | | `remove_sheet_pin` | Remove a pin from a hierarchical sheet block | | `duplicate_sheet` | Duplicate a sheet, copying the child file with new UUIDs | | `reorder_sheet_pages` | Reorder sheets by specifying the desired UUID order | **Hierarchy inspection** | Tool | Description | |------|-------------| | `is_root_schematic` | Check whether a schematic is the root or a sub-sheet | | `list_hierarchy` | List the full sheet hierarchy tree from root | | `get_sheet_info` | Get sheet details with pin and label matching status | | `validate_hierarchy` | Check for orphaned labels and pins, direction mismatches, duplicate refs | **Cross-sheet analysis** | Tool | Description | |------|-------------| | `trace_hierarchical_net` | Trace a net across the hierarchy through pins and labels | | `list_cross_sheet_nets` | List all nets crossing sheet boundaries | | `get_symbol_instances` | List symbol instances from the root schematic | **Annotation, export, utilities** | Tool | Description | |------|-------------| | `annotate_schematic` | Auto-assign reference designators, respecting hierarchy | | `export_hierarchical_netlist` | Export a netlist with hierarchy info (requires `kicad-cli`) | | `flatten_hierarchy` | Flatten a hierarchical schematic into a single sheet | | `run_jobset` | Run a KiCad jobset file | | `get_version` | Get KiCad version information |

Symbol and footprint libraries (9 tools)

**Symbol** | Tool | Description | |------|-------------| | `list_lib_symbols` | List all symbols in a `.kicad_sym` library | | `get_symbol_info` | Get detailed pin and property info for a library symbol | | `add_symbol` | Add a new symbol to a `.kicad_sym` library | | `export_symbol_svg` | Export a symbol library to SVG images | | `upgrade_symbol_lib` | Upgrade a symbol library to the current KiCad format | **Footprint** | Tool | Description | |------|-------------| | `list_lib_footprints` | List all footprints in a `.pretty` library directory | | `get_footprint_info` | Get pad and outline details for a `.kicad_mod` file | | `export_footprint_svg` | Export a footprint to SVG | | `upgrade_footprint_lib` | Upgrade a footprint library to the current KiCad format |

## Debugging Drive the servers by hand with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector): ```bash npx @modelcontextprotocol/inspector uvx --from mcp-server-kicad mcp-server-kicad ``` ## Contributing Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, and [docs/adr-cst-substrate.md](docs/adr-cst-substrate.md) for the architecture decisions behind the byte-preserving write path. - [Report a bug](https://github.com/ProductOfAmerica/mcp-server-kicad/issues/new) - [Browse open issues](https://github.com/ProductOfAmerica/mcp-server-kicad/issues) - [Security policy](SECURITY.md) ## License [MIT](LICENSE)