pcb-mcp
# pcb-mcp
An MCP server that lets an AI assistant read and modify KiCAD PCB designs through KiCAD's IPC API.
## Status
Pre-alpha. There is no working code yet. This is actively being built as a personal learning project and is not usable today. It is not installable.
## What it will do
The server exposes a small set of tools (20 or fewer) so an AI assistant can pick the right one reliably:
- Query board state (layers, nets, footprints, tracks, zones)
- Place and move footprints
- Create tracks and vias
- Run Design Rule Check (DRC)
- Export manufacturing files (Gerbers, drill files, BOM)
## Design decisions
| Choice | Reason |
|--------|--------|
| Python 3.11+ | Matches KiCAD plugin ecosystem, broad library support |
| Official `mcp` SDK v2 (`MCPServer`, stdio transport) | Canonical implementation, stable as of 2026-07-28 |
| `kicad-python` over the KiCAD IPC API | MIT-licensed, actively maintained, replaces deprecated SWIG `pcbnew` bindings |
| KiCAD 10.0.x target | Current stable (10.0.5). IPC API first shipped in KiCAD 9 but matured in 10 |
| PCB editor scope only | The IPC API has no schematic access today |
| MIT license (out-of-process client) | No GPL entanglement because the server communicates over IPC, not linked to KiCAD |
## Requirements
- **KiCAD 10.0.x** installed and running with a board open. The IPC API needs a live GUI instance (headless mode is expected in KiCAD 11).
- **KiCAD API enabled** in Preferences → API settings.
- **Python 3.11+**
- Only one IPC client can attach to a KiCAD instance at a time.
## Development
This project follows a branch-and-pull-request workflow. The `main` branch is protected, and every change lands through a PR.
Detailed planning and research documents are kept locally and are not published in this repo. The README is the single source of project context for external readers.
## License
MIT. See [LICENSE](LICENSE).
TDQS
Scored across 14 tools
Each tool targets a distinct resource and action: board info, footprints (list/get/move/edit), nets (list/get connections), tracks (list/create), zones (list/manage), vias (create), stats, and design rules. There is no overlap or ambiguity between tool purposes.
All tools follow a consistent verb_noun pattern in snake_case: list_zones, get_board_info, list_footprints, get_footprint, list_nets, get_net_connections, list_tracks, get_board_stats, get_design_rules, move_footprint, create_track, create_via, manage_zone, edit_footprint. The get_ vs list_ distinction is systematic.
14 tools is well within the ideal range for a PCB design server. Each tool serves a clear purpose without redundancy, covering board-level information, component/nets/tracks/zones/vias operations, and design rule queries. The count feels appropriately scoped for the domain.
The tool surface covers reading board data and performing basic edits (move/edit footprint, create track/via, manage zones), but lacks deletion for tracks and vias, and there is no tool to list or query individual vias. This leaves notable gaps for a full PCB editing workflow, though core inspection and simple modifications are supported.