kicad-mcp-server
🔌 MCP server for KiCad EDA - Analyze schematics & PCBs, trace pin-level connections, automate design editing. Works with any MCP-compatible AI tool
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/seeed-studio--kicad-mcp-server)HTML
<a href="/listings/seeed-studio--kicad-mcp-server"><img src="/api/listings/seeed-studio--kicad-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Recommended: Install into KiCad Python (Full PCB Analysis)
KiCad ships with its own Python that includes the `pcbnew` module. Installing into this Python gives you full PCB analysis capabilities (precise track lengths, via statistics, signal integrity, power integrity).
**Step 1**: Find your KiCad Python path:
| Platform | Path | |----------|------| | Windows | `C:\Program Files\KiCad\<version>\bin\python.exe` | | macOS | `/Applications/KiCad/KiCad.app/Contents/Frameworks/python3` | | Linux | `/usr/bin/python3` (if kicad python bindings installed) |
**Step 2**: Install the package into KiCad Python:
# Windows example (KiCad 10.0) "C:\Program Files\KiCad\10.0\bin\python.exe" -m pip install fastmcp "C:\Program Files\KiCad\10.0\bin\python.exe" -m pip install -e . # macOS example /Applications/KiCad/KiCad.app/Contents/Frameworks/python3 -m pip install fastmcp /Applications/KiCad/KiCad.app/Contents/Frameworks/python3 -m pip install -e .
**Step 3**: Configure MCP to use KiCad Python (see Configuration section below).
Fallback: Install into System Python (Limited PCB Analysis)
If you skip KiCad Python setup, the server still works but falls back to text-based PCB parsing. You get basic data (track counts, net names, widths) but lose precise lengths, design rules, and signal integrity analysis.
pip install -e .
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 318 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # KiCad MCP Server
- A Model Context Protocol (MCP) server for KiCad 9.0+ that lets AI assistants analyze schematics, inspect PCBs, trace connections, validate designs, and generate embedded code.
- ## Features
- - **Schematic Analysis** - Components, nets, symbols, hierarchical sheets
- - **PCB Analysis** - Footprints, tracks, routing quality, signal/power integrity via pcbnew API
- - **Netlist Tracing** - 100% accurate pin-level connection tracking
- - **Design Validation** - ERC/DRC via kicad-cli (headless, CI friendly)
- - **Pin Analysis** - Pin function detection, conflict analysis, pinmux config
- - **Code Generation** - Device tree (.dts) and hardware test code generation
- - **Project Management** - Create KiCad projects from templates
- - **Parts Registry** - Search 21,000+ verified parts on an open, no-login registry ([PartReel](https://partreel.com) by default, `PARTS_REGISTRY_URL` to change) and download footprints/symbols/3D into the project; downloads are host-allowlisted, extension-checked and size-capped
- ## Requirements
- - KiCad 8.0+ (9.0 or 10.0 recommended)
- - `kicad-cli` in PATH (included with KiCad)
- ## Installation
- ### Recommended: Install into KiCad Python (Full PCB Analysis)
- KiCad ships with its own Python that includes the `pcbnew` module. Installing into this Python gives you full PCB analysis capabilities (precise track lengths, via statistics, signal integrity, power integrity).
- **Step 1**: Find your KiCad Python path:
- | Platform | Path |
- |----------|------|
- | Windows | `C:\Program Files\KiCad\<version>\bin\python.exe` |
- | macOS | `/Applications/KiCad/KiCad.app/Contents/Frameworks/python3` |
- | Linux | `/usr/bin/python3` (if kicad python bindings installed) |
- **Step 2**: Install the package into KiCad Python:
- ```bash
- # Windows example (KiCad 10.0)
- "C:\Program Files\KiCad\10.0\bin\python.exe" -m pip install fastmcp
- "C:\Program Files\KiCad\10.0\bin\python.exe" -m pip install -e .
- # macOS example
- /Applications/KiCad/KiCad.app/Contents/Frameworks/python3 -m pip install fastmcp
- /Applications/KiCad/KiCad.app/Contents/Frameworks/python3 -m pip install -e .
- ```
- **Step 3**: Configure MCP to use KiCad Python (see Configuration section below).
- ### Fallback: Install into System Python (Limited PCB Analysis)
- If you skip KiCad Python setup, the server still works but falls back to text-based PCB parsing. You get basic data (track counts, net names, widths) but lose precise lengths, design rules, and signal integrity analysis.
- ```bash
- pip install -e .
- ```
- ## Configuration
- ### Claude Desktop
- Edit your config file:
- - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- - **Linux**: `~/.config/Claude/claude_desktop_config.json`
- **With KiCad Python (recommended):**
- ```json
- {
- "mcpServers": {
- "kicad": {
- "type": "stdio",
- "command": "C:\\Program Files\\KiCad\\10.0\\bin\\python.exe",
- "args": ["-m", "kicad_mcp_server"],
- "cwd": "C:\\Users\\YourName\\Desktop\\kicad-mcp-server"
- }
- }
- }
- ```
- **With system Python (fallback):**
- ```json
- {
- "mcpServers": {
- "kicad": {
- "type": "stdio",
- "command": "python",
- "args": ["-m", "kicad_mcp_server"],
- "cwd": "C:\\Users\\YourName\\Desktop\\kicad-mcp-server"
- }
- }
- }
- ```
- ### Claude Code CLI
- ```bash
- # With KiCad Python (recommended)
- claude mcp add kicad -s user -- "C:\Program Files\KiCad\10.0\bin\python.exe" -m kicad_mcp_server
- # With system Python (fallback)
- claude mcp add kicad -s user -- python -m kicad_mcp_server
- ```
- ### Cursor / Windsurf / Other MCP Clients
- Use the same config structure with your client's MCP settings. Point `command` to KiCad Python for full analysis, or `python` for fallback mode.
- ### Verify Installation
- After restarting your AI client, ask it:
- > "What tools are available for KiCad?"
- You should see a list of KiCad MCP tools. To verify pcbnew is working:
- > "Get PCB statistics for MyBoard.kicad_pcb"
- If the response shows **Design Rules** section with clearance/width values, pcbnew is active. If it shows **board dimensions as approximation**, you're in text-only mode.
- Common issues:
- 1. KiCad is installed and `kicad-cli` is accessible
- 2. The `cwd` path in your config points to the correct directory
- 3. Python can import the package (`python -c "import kicad_mcp_server"`)
- ## Usage
- Once configured, you can interact with your KiCad projects through natural language in your AI assistant. Below are common workflows.
- ### 1. Analyze a Schematic
- Point the AI to your `.kicad_sch` file and ask questions:
- > "List all components in C:\Projects\MyBoard\MyBoard.kicad_sch"
- > "Show me all the power nets in MyBoard.kicad_sch"
- > "Find all resistors with value 10k"
- The AI will call tools like `list_schematic_components`, `list_schematic_nets`, `search_symbols` behind the scenes.
- ### 2. Trace Connections (Netlist-based)
- First export a netlist, then trace connections with pin-level accuracy:
- > "Generate a netlist from MyBoard.kicad_sch"
- > "Trace all connections from U1"
- > "What pins are connected to the I2C_SDA net?"
- This uses `generate_netlist` and `trace_netlist_connection` for 100% accurate results.
- ### 3. Validate Your Design
- Run electrical and design rule checks:
- > "Run ERC on MyBoard.kicad_sch and show me any errors"
- > "Run DRC on MyBoard.kicad_pcb"
- > "Are there any unconnected pins?"
- Uses `run_erc`, `run_drc`, and `detect_pin_conflicts`.
- ### 4. Analyze PCB
- > "Get statistics for MyBoard.kicad_pcb"
- > "List all footprints on the top layer"
- > "Find all tracks on the VDD_nRF net"
- > "Analyze PCB routing quality"
- > "Check signal integrity - are USB differential pairs length-matched?"
- > "Analyze power integrity - how's the GND coverage?"
- ### 5. Create a New Project
- > "Create a new KiCad project called LED_Blinker in C:\Projects"
- > "Add a 1k resistor called R1 to the schematic"
- > "Add an LED called D1"
- > "Add a wire from R1 pin 2 to D1 pin 1"
- ### 6. Pin Analysis and Code Generation
- > "Analyze pin functions for U1 in MyBoard.kicad_sch"
- > "Detect any pin conflicts in the design"
- > "Generate a device tree file for the STM32 on this board"
- > "Generate pytest hardware tests for all I2C devices"
- ## Available Tools Reference
- ### Schematic Analysis
- | Tool | Description |
- |------|-------------|
- | `list_schematic_components` | List components with filtering by type, value, or DNP status |
- | `list_schematic_nets` | List all nets, optionally filter power nets |
- | `get_schematic_info` | Project metadata and statistics |
- | `search_symbols` | Search components by pattern (regex) |
- | `get_symbol_details` | Detailed info for a specific component |
- ### PCB Analysis
- | Tool | Description |
- |------|-------------|
- | `list_pcb_footprints` | List footprints with optional layer filter |
- | `get_pcb_statistics` | Board dimensions, layer count, design rules |
- | `find_tracks_by_net` | Track segments, lengths, widths, vias for a specific net |
- | `analyze_pcb_nets` | Routing analysis: width/via distribution, net length ranking |
- | `analyze_pcb_signal_integrity` | Diff pair matching, RF traces, longest signal nets |
- | `analyze_pcb_power_integrity` | Power zones, GND coverage, power routing analysis |
- ### Netlist Analysis
- | Tool | Description |
- |------|-------------|
- | `generate_netlist` | Export netlist from schematic via kicad-cli |
- | `trace_netlist_connection` | Trace all connections from a component/pin |
- | `get_netlist_nets` | List all nets with pin connections |
- | `get_netlist_components` | List components with their net connections |
- ### Validation
- | Tool | Description |
- |------|-------------|
- | `run_erc` | Electrical Rules Check on schematic |
- | `run_drc` | Design Rules Check on PCB |
- | `detect_pin_conflicts` | Find conflicting pin connections |
- ### Editing
- | Tool | Description |
- |------|-------------|
- | `create_kicad_project` | Create an empty project (default) or one from a KiCad template (`template="Arduino_Uno"`) |
- | `add_component_from_library` | Add component with symbol from library |
- | `add_wire` | Add wire connection |
- | `add_label` | Add local label |
- | `setup_pcb_layout` | Initialize PCB with dimensions |
- | `export_gerber` | Export Gerber files |
- ## Editing Limitations
- Schematic editing is **experimental**. KiCad has no Python API for schematic editing, so tools use manual S-expression manipulation. When adding components via `add_component_from_library`, the tool automatically reads the symbol definition from KiCad's library files and inserts it into the schematic — this ensures proper rendering.
- Known limitations:
- - Wire connections may not form perfect electrical connections
- - Visual alignment is basic
- - KiCad must be closed and reopened to see file changes (no hot-reload)
- **Recommendation**: Use KiCad GUI for design work. Use this MCP server for analysis, validation, and code generation.
- ## Troubleshooting
- ### "KiCad template not found" / "KiCad's Python (pcbnew) not found"
- Make sure KiCad is installed at the standard path:
- - **Windows**: `C:\Program Files\KiCad\<version>\`
- - **macOS**: `/Applications/KiCad/`
- - **Linux**: `/usr/share/kicad/`
- `create_kicad_project` writes empty projects with KiCad's own `pcbnew` module, using KiCad's bundled Python when the server runs under another interpreter. For a non-standard install, set `KICAD_PYTHON` to KiCad's python executable.
- ### "kicad-cli not found"
- Add KiCad's bin directory to your PATH:
- ```bash
- # Windows example
- set PATH=%PATH%;C:\Program Files\KiCad\10.0\bin
- # Linux/macOS example
- export PATH="/usr/bin:$PATH"
- ```
- ### "pcbnew module not found" / PCB analysis is limited
- pcbnew is only available in KiCad's bundled Python. Two options:
- **Option A (recommended)**: Configure MCP to use KiCad Python — see [Installation](#recommended-install-into-kicad-python-full-pcb-analysis).
- **Option B**: Accept text-only mode. You'll still get basic PCB data (footprints, track counts, net names) but without precise lengths or design rules.
- ### Python 3.14 install fails
- Make sure you have `pip >= 26.0`:
- ```bash
- pip install --upgrade pip
- pip install -e .
- ```
- ## Resources
- - [KiCad Documentation](https://docs.kicad.org/)
- - [KiCad File Format Spec](https://dev-docs.kicad.org/en/file-formats/)
- - [Model Context Protocol](https://modelcontextprotocol.io/)
- - [kicad-cli Documentation](https://docs.kicad.org/en/cli/)
- ## Acknowledgments
- Thanks to all contributors and community feedback:
- - [@raffaeler](https://github.com/raffaeler) for KiCad 10 compatibility testing and feedback (#9)
- - [@shivam5594](https://github.com/shivam5594) for Python 3.14 install issue report (#11)
- - [@derekc00](https://github.com/derekc00) for lint fixes (#10)
- - [@befedo](https://github.com/befedo) for SchematicComponent dataclass access bug report and patch (#13)
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.