Metadata-Version: 2.4
Name: kicad-eda-mcp
Version: 0.1.0
Summary: MCP server for controlling KiCad EDA software — IPC API + CLI + SWIG, with auto-launch.
Author: KiCad-EDA-MCP Contributors
License-Expression: MIT
Project-URL: Documentation, https://github.com/Akhil-Chaturvedi/KiCad-EDA-MCP/blob/main/README.md
Project-URL: Issues, https://github.com/Akhil-Chaturvedi/KiCad-EDA-MCP/issues
Keywords: kicad,mcp,eda,pcb,schematic,model-context-protocol,ai,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.2.0
Requires-Dist: kicad-python>=0.5.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: kicad-sch-api>=0.2.0
Requires-Dist: tabulate>=0.9.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"

# KiCad MCP Server

A Model Context Protocol (MCP) server for controlling KiCad EDA software —
schematics, PCBs, manufacturing outputs, design checks, and library management —
through any MCP-compatible AI assistant.

The server exposes 22 routers containing ~280-306 operations (the spread is
because the routing router exposes 8-30 operations depending on the installed
Java version). All operations return structured `{ok, message, error, data}`
dicts.

## How It Works

The server controls KiCad through three layers:

- **IPC API** (`kicad-python` / kipy): live board and project control.
  Requires a running KiCad GUI instance with IPC enabled (KiCad 9+).
  Handles reads, mutations, and interactive operations.
- **kicad-cli**: headless export, DRC, ERC, import, and file upgrades.
  No GUI needed. Handles all manufacturing output formats.
- **SWIG pcbnew** (legacy): direct board manipulation via KiCad's bundled
  Python bindings. Deprecated since KiCad 9, removed in KiCad 11. Only
  loads when KiCad's bundled Python is the interpreter.

A fourth layer — `kicad-sch-api` — provides pure-Python schematic editing
with no KiCad instance required.

On Windows, the server can auto-launch KiCad as a detached background process.

## Installation

**From PyPI:**

```bash
pip install kicad-eda-mcp
# Optional: HTTP/SSE transport (remote/multi-client)
pip install uvicorn starlette
```

**From source (development):**

```bash
pip install -e ".[dev]"
```

## Quick Start

### Any MCP client (stdio)

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "kicad": {
      "type": "stdio",
      "command": "kicad-eda-mcp"
    }
  }
}
```

### With mutations enabled

```bash
python -m kicad_mcp --enable-mutations
```

### HTTP/SSE mode (multi-client)

```bash
python -m kicad_mcp --http --port 8765
```

Requires `uvicorn` and `starlette` (install separately — not in the default
dependencies).

### Progressive disclosure (context economy)

```bash
python -m kicad_mcp --tool-mode dynamic
```

Exposes only `kicad_discover`, `kicad_load_toolset`, `kicad_unload_toolset`
plus the always-loaded `kicad_system` and `kicad_calculator` routers. The LLM
loads additional toolsets on demand:

```
kicad_load_toolset(name="board")
```

## Available Routers

| Router | Ops | Backend | Purpose |
|--------|-----|---------|---------|
| `kicad_system` | 12 | CLI/IPC | Connection, version, documents, capabilities, multi-instance management |
| `kicad_project` | 5 | IPC | Project text variables, net classes |
| `kicad_board` | 53 | IPC | PCB CRUD, queries, mutations, footprint ops, layer control |
| `kicad_board_export` | 27 | CLI | All PCB export formats (Gerbers, PDF, SVG, STEP, drill, position, etc.) |
| `kicad_board_check` | 1 | CLI | Design Rule Check (DRC) |
| `kicad_schematic` | 10 | CLI | ERC + exports (PDF/BOM/netlist/SVG/DXF) |
| `kicad_schematic_edit` | 51 | kicad-sch-api | Pure-Python schematic editing (no KiCad needed) |
| `kicad_footprint` | 10 | CLI/git | SVG export, upgrade, parametric generation, IPC pad calc |
| `kicad_symbol` | 8 | CLI/git | SVG export, upgrade, STM32/AVR/connector symbol generation |
| `kicad_gerber` | 3 | CLI | Gerber convert/diff/info |
| `kicad_jobset` | 1 | CLI | Jobset execution |
| `kicad_library` | 30 | CLI/git | Search, KLC checks, file format editing, visual diff |
| `kicad_swig` | 7 | SWIG | Legacy pcbnew operations (KiCad <=10) |
| `kicad_analysis` | 5 | IPC/CLI | Signal/power integrity, pin analysis, routing quality, SPICE |
| `kicad_analysis_tools` | 14 | CLI/IPC | SI/PI/EMC calculators, design lint, pin function analysis |
| `kicad_codegen` | 0 | — | Device tree / test code generation (disabled stubs) |
| `kicad_calculator` | 10 | pure math | PCB calculators (track width, via, RF, impedance, etc.) |
| `kicad_workflow` | 6 | CLI | High-level composers (manufacturing package, design check, etc.) |
| `kicad_worksheet` | 5 | pure Python | .kicad_wks worksheet parsing and creation |
| `kicad_routing` | 8-30 | CLI/API | Algorithmic routing via Freerouting (Java-dependent) |
| `kicad_quality_gates` | 13 | CLI/IPC | Cascading quality gates, checkpoints, DRC progress |
| `kicad_placement` | 5 | IPC/sch-api | Force-directed PCB and schematic auto-placement |

**Total: 22 routers, 276 fixed operations + 8-30 routing operations**
(284 without Java, 306 with Java 21+).

## Tool Modes and Discovery

The server supports three tool exposure modes:

| Mode | Visible tools | Use case |
|------|--------------|----------|
| `dynamic` | 3 meta-tools + always-loaded routers | Context economy — LLM loads toolsets on demand |
| `router` (default) | All 22 routers | Balanced — each router is one tool with an `operation` parameter |
| `full` | All operations as individual tools | Future expansion (same as router for now) |

### Meta-tools (available in all modes)

| Meta-tool | Description |
|-----------|-------------|
| `kicad_discover` | List all toolsets with descriptions and load status |
| `kicad_load_toolset` | Load a toolset by name (triggers background dependency check) |
| `kicad_unload_toolset` | Unload a toolset to free context space |
| `kicad_set_profile` | Switch to a pre-defined profile (see below) |
| `kicad_get_capabilities` | Report total routers, operations, dependency status |
| `kicad_search_tools` | Search all operations by keyword |

### Profiles

Pre-defined toolset combinations for common workflows:

| Profile | Toolsets included |
|---------|-------------------|
| `read-only` | system, calculators, exports, analysis, libraries |
| `minimal` | system, calculators |
| `build` | system, calculators, board, schematic, schematic_edit, routing, workflow, exports, analysis |
| `schematic_only` | system, calculators, schematic, schematic_edit, libraries, workflow |
| `pcb_only` | system, calculators, board, exports, routing, analysis, workflow |
| `manufacturing` | system, calculators, exports, libraries, workflow |
| `high_speed` | system, calculators, board, analysis, routing, workflow |
| `power` | system, calculators, board, analysis, exports, workflow |
| `simulation` | system, calculators, analysis, schematic, workflow |
| `analysis` | system, calculators, analysis, board, exports, workflow |
| `expert` | All toolsets including legacy SWIG |

## Dependencies

### Installed at `pip install` time (hard dependencies)

These are in `pyproject.toml` and installed automatically:

| Package | Purpose |
|---------|---------|
| `mcp>=1.2.0` | MCP SDK (server, transport, types) |
| `kicad-python>=0.5.0` | IPC API client (kipy) for live board control |
| `kicad-sch-api>=0.2.0` | Pure-Python schematic editing |
| `psutil>=5.9.0` | Process management for auto-launch/supervisor |
| `tabulate>=0.9.0` | Required by the footprint generator for `list_generators`/`generate_footprint` |

### Optional dependencies

| Package | Install command | Purpose |
|---------|----------------|---------|
| `uvicorn`, `starlette` | `pip install uvicorn starlette` | HTTP/SSE transport |
| `cadquery` | `pip install cadquery` | STEP 3D model diff and audit |

The server includes a fallback self-heal mechanism (`deps.py`): if a hard
dependency is somehow missing at runtime, it attempts a `pip install` in the
background when the corresponding toolset is loaded. This is a safety net, not
the primary install path.

### Clone-on-demand library repositories

Library utility operations (KLC checks, footprint generation, symbol
generation) require two GitLab repositories that are not bundled with KiCad:

- [`kicad-library-utils`](https://gitlab.com/kicad/libraries/kicad-library-utils) — KLC checks, file format modules, symbol generators
- [`kicad-footprint-generator`](https://gitlab.com/kicad/libraries/kicad-footprint-generator) — Parametric footprint generation

These are auto-cloned to `~/.cache/kicad-eda-mcp/` on first use and updated
periodically (every 24 hours by default). Requires `git` in PATH.

Check status:

```
kicad_library → lib_status
```

### Freerouting (algorithmic routing)

The routing router uses Freerouting, which requires Java:

- CLI pipeline (DSN export, autoroute, SES import): Java 17+
- API server pipeline (REST, sessions, jobs): Java 21+

If Java is not installed, only the 8 Java-independent routing operations
(analysis, cleanup, status check) are visible. Use
`download_java_for_routing` to auto-download a JRE from Adoptium, then
restart the MCP server.

The Freerouting JAR is auto-downloaded from GitHub releases on first use.

## Resources

Browsable context available without a tool call:

| Resource | Description |
|----------|-------------|
| `kicad://capabilities` | System capabilities and available control layers |
| `kicad://layers` | Complete list of board layer names and IDs |
| `kicad://export-formats` | All available export formats |
| `kicad://calculators` | Available PCB calculators |
| `kicad://klc-rules` | KiCad Library Convention rules (S/F/G/M categories, 84 rules) |
| `kicad://spice-models` | Built-in SPICE simulation models (opamp, varistor, potentiometer) |
| `kicad://library-utils` | Available KLC check and library management operations |
| `kicad://quality-gates` | Available quality gate operations and descriptions |
| `kicad://subcircuit-templates` | Pre-built circuit templates for rapid design |

## Key Operations by Category

### KLC compliance checks (`kicad_library`)

| Operation | Description |
|-----------|-------------|
| `check_klc_symbol` | Validate symbols against 20+ KLC rules (S3-S7, EC01-03, G1) |
| `check_klc_footprint` | Validate footprints against 18+ KLC rules (F5-F9, EC01, G1) |
| `check_3d_coverage` | Audit which footprints have 3D models |
| `compare_libraries` | Diff two library versions (added/removed/changed) |
| `check_lib_table` | Validate library table files |

### Footprint/symbol file editing (`kicad_library`)

| Operation | Description |
|-----------|-------------|
| `parse_footprint` | Load `.kicad_mod` and return structure (pads, graphics, 3D models) |
| `create_footprint` | Create new footprint programmatically |
| `edit_footprint` | Modify existing footprint (name, description, tags) |
| `parse_symbol_library` | Load `.kicad_sym` and list symbols with properties/pins |
| `create_symbol` | Create new symbol in a library |
| `edit_symbol` | Modify existing symbol properties |

### Symbol generation (`kicad_symbol` + `kicad_library`)

| Operation | Description |
|-----------|-------------|
| `generate_symbol_from_csv` | Create symbol from CSV pinout table |
| `generate_stm32` | Generate STM32 symbols from STM32CubeMX XML |
| `generate_avr` | Generate AVR DA/DB symbols from IO mux CSV |
| `generate_connector` | Generate connector symbols |
| `generate_resistor_network` | Generate resistor network symbols |
| `generate_dip_switch` | Generate DIP switch symbols |

### Parametric footprint generation (`kicad_footprint`)

| Operation | Description |
|-----------|-------------|
| `list_generators` | List available generators (gullwing, no_lead, BGA, DIP, connectors, etc.) |
| `generate_footprint` | Generate IPC-7351 compliant footprint with 3D model |
| `generate_batch` | Batch generate multiple footprints in parallel |
| `dry_run_generation` | Preview without writing files |
| `calc_ipc_pad` | Calculate IPC-7351 pad dimensions (gullwing/nolead, 3 density levels) |

### Visual diff (`kicad_library`)

| Operation | Description |
|-----------|-------------|
| `visual_library_diff` | Generate HTML visual diff with renders and overlays |
| `diff_symbols` | Text diff between two symbols |
| `diff_yaml` | Diff YAML generator spec files |
| `compare_sexpr` | Normalize and compare S-expression files |

### Quality gates (`kicad_quality_gates`)

| Operation | Description |
|-----------|-------------|
| `project_quality_gate` | Top-level cascading gate: runs all sub-gates, returns PASS/FAIL/BLOCKED |
| `schematic_quality_gate` | Check schematic completeness (missing footprints, unannotated, empty values) |
| `schematic_connectivity_gate` | Check net connectivity (unconnected pins, single-pin nets) |
| `pcb_quality_gate` | Check PCB design rules via DRC |
| `pcb_placement_quality_gate` | Check placement geometry (overlaps, off-board, courtyard) |
| `pcb_transfer_quality_gate` | Check schematic-to-PCB net parity |
| `manufacturing_quality_gate` | Check manufacturing readiness (drill sizes, annular rings) |
| `design_review_snapshot` | One-call review: board info, nets, DRC, footprints, stats |
| `project_checkpoint` | Snapshot project files to a timestamped backup |
| `project_restore_checkpoint` | Restore project files from a checkpoint |

## Common Workflows

### Export manufacturing files

```
kicad_workflow → export_manufacturing_package
  pcb_file: "myboard.kicad_pcb"
  output_dir: "fab/"
```

### Run design checks

```
kicad_workflow → full_design_check
  sch_file: "mysch.kicad_sch"
  pcb_file: "myboard.kicad_pcb"
```

### Calculate track width

```
kicad_calculator → track_width
  current_a: 2.0
  temp_rise_c: 10
  layer: "external"
```

### Calculate IPC-7351 pad dimensions

```
kicad_footprint → calc_ipc_pad
  package_type: "gullwing"
  body_length: 5.0
  body_width: 4.4
  lead_width: 0.42
  density_level: "nominal"
```

### Check KLC compliance

```
kicad_library → check_klc_symbol
  library_path: "mylib.kicad_sym"
  verbose: 2

kicad_library → check_klc_footprint
  footprint_paths: "SOIC-8.kicad_mod"
  verbose: 2
```

### Generate footprint from parametric generator

```
kicad_footprint → generate_footprint
  generator: "package/gullwing"
  part: "SOT-23"
  output_dir: "footprints/"
```

### Generate symbol from CSV

```
kicad_library → generate_symbol_from_csv
  csv_path: "pinout.csv"
  output_path: "mysym.kicad_sym"
```

### Run the full quality gate

```
kicad_quality_gates → project_quality_gate
  pcb_file: "myboard.kicad_pcb"
  sch_file: "mysch.kicad_sch"
```

## Configuration

### Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `KICAD_MCP_ENABLE_MUTATIONS` | `0` | Enable write operations (0=read-only, 1=writes allowed) |
| `KICAD_MCP_DRY_RUN_DEFAULT` | `1` | Default dry_run for mutations unless explicitly overridden |
| `KICAD_MCP_AUTO_LAUNCH` | `1` | Auto-launch KiCad if not running |
| `KICAD_MCP_IDLE_TTL` | `1800` | Auto-shutdown KiCad after N seconds idle (0=never) |
| `KICAD_MCP_SUPERVISOR_INTERVAL` | `60` | Health-check interval for the supervisor (seconds) |
| `KICAD_API_SOCKET` | auto | Override IPC socket path |
| `KICAD_API_TOKEN` | auto | Override IPC authentication token |
| `KICAD_MCP_CLIENT_NAME` | `kicad-eda-mcp` | Client name reported to KiCad |
| `KICAD_MCP_IPC_TIMEOUT_MS` | `60000` | Timeout for IPC API requests (milliseconds) |
| `KICAD_MCP_IPC_CONNECT_RETRIES` | `10` | Max retries when connecting to the IPC socket |
| `KICAD_MCP_IPC_CONNECT_DELAY` | `0.5` | Delay between IPC connect retries (seconds) |
| `KICAD_BIN_PATH` | auto | Override KiCad executable path |
| `KICAD_CLI_PATH` | auto | Override kicad-cli path |
| `KICAD_PYTHON_PATH` | auto | Override KiCad bundled Python path (for SWIG) |
| `KICAD_MCP_LIB_CACHE_DIR` | `~/.cache/kicad-eda-mcp` | Cache directory for cloned library repos |
| `KICAD_MCP_LIB_UPDATE_INTERVAL` | `86400` | Seconds between library repo updates (0=pull every call) |
| `KICAD_MCP_LOG_LEVEL` | `INFO` | Logging level: DEBUG, INFO, WARNING, ERROR |
| `KICAD_MCP_LOG_FILE` | none | Log file path (default: stderr only) |
| `KICAD_MCP_HTTP_HOST` | `127.0.0.1` | HTTP bind host |
| `KICAD_MCP_HTTP_PORT` | `8765` | HTTP port |
| `KICAD_MCP_COMMIT_PREFIX` | `KiCad MCP` | Commit message prefix for mutation operations |

### CLI flags

```bash
python -m kicad_mcp [options]

  --http                Run in HTTP/SSE mode (default: stdio)
  --host HOST           HTTP bind host (default: 127.0.0.1)
  --port PORT           HTTP port (default: 8765)
  --editor-type TYPE    Scope tools to an editor: all|schematic|pcb|symbol|footprint
                        (default: all). NOTE: filtering is not yet implemented —
                        the flag is accepted but has no effect.
  --tool-mode MODE      Tool visibility: dynamic|router|full (default: router)
  --enable-mutations    Allow write operations (default: read-only)
  --auto-launch on|off  Auto-launch KiCad if not running (default: on)
  --log-level LEVEL     Logging level: DEBUG|INFO|WARNING|ERROR (default: INFO)
```

## Requirements

- KiCad 9+ (10 recommended for full IPC API support)
- Python 3.10+
- `kicad-cli` in PATH (included with KiCad)
- `git` in PATH (for clone-on-demand library repos)
- For algorithmic routing: Java 17+ (CLI pipeline) or Java 21+ (API server)

## Known Limitations

These are inherent to KiCad's version or are unimplemented features, verified
against KiCad 10.0.5 and the official KiCad documentation.

### Gerber tool (`kicad_gerber`)

KiCad's `kicad-cli` has no `gerber` or `gerbview` subcommand (only `fp`,
`jobset`, `pcb`, `sch`, `sym`, `version`). Gerber viewing/conversion/diff is a
GUI-only (GerbView) feature. The `kicad_gerber` router detects this and returns
a clear error pointing to alternatives (GerbView GUI, `gerbv`, or a Python
Gerber library). This is an upstream KiCad limitation, not a bug in this server.

### Board PNG export

`pcb export png` is documented in the KiCad master branch but is absent from
the installed KiCad 10.0.x CLI. The export router detects the supported-format
list at runtime and returns a clear error suggesting `svg` or `pdf` instead.
PNG export will work once KiCad adds the `png` subcommand to the CLI.

### SWIG backend (`kicad_swig`)

The SWIG-based `pcbnew` Python bindings are deprecated since KiCad 9.0 and are
scheduled for removal in KiCad 11. The SWIG backend only loads when KiCad's
bundled Python is used as the interpreter; with a system Python (the common
case), `swig_pcbnew` reports as unavailable. The IPC API is the supported
replacement for KiCad 10+. The `autoroute`, `panelize`, and `silkscreen_fix`
operations under `kicad_swig` are unimplemented stubs.

### IPC API scope (KiCad 9/10)

Per the KiCad developer documentation, the IPC API in KiCad 9 and 10 supports
communication with a running GUI instance only. Headless mode via
`kicad-cli api-server` is a KiCad 11 feature. The IPC API in KiCad 9/10 has no
support for plotting or exporting files from designs (also added in KiCad 11);
exports are handled by the `kicad-cli` backend instead. There is no IPC-based
autorouter or panelizer in any KiCad version.

### Code generation (`kicad_codegen`)

The `device_tree` and `test_code` operations are unimplemented stubs. They
return a descriptive message but do not parse the schematic or generate any
file. Device-tree and test-scaffold generation are not KiCad features;
implementing them is future work.

### Editor-type filtering (`--editor-type`)

The `--editor-type` flag is accepted by the CLI but tool filtering is not yet
implemented. All routers are exposed regardless of the value passed. This is
reserved for future use.

### Mutations

Board and project write operations (add tracks/vias/text/footprints, place
footprints, commit/save) are disabled by default for safety. Set
`KICAD_MCP_ENABLE_MUTATIONS=1` (or pass `--enable-mutations`) to enable them.
Every mutation supports `dry_run=true` to preview without writing.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and code
style guidelines.

## License

MIT. See [LICENSE](LICENSE).
