Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/seeed-studio--kicad-mcp-server/badge.svg)](/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

i

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)

  1. # KiCad MCP Server
  2. 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.
  3. ## Features
  4. - **Schematic Analysis** - Components, nets, symbols, hierarchical sheets
  5. - **PCB Analysis** - Footprints, tracks, routing quality, signal/power integrity via pcbnew API
  6. - **Netlist Tracing** - 100% accurate pin-level connection tracking
  7. - **Design Validation** - ERC/DRC via kicad-cli (headless, CI friendly)
  8. - **Pin Analysis** - Pin function detection, conflict analysis, pinmux config
  9. - **Code Generation** - Device tree (.dts) and hardware test code generation
  10. - **Project Management** - Create KiCad projects from templates
  11. - **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
  12. ## Requirements
  13. - KiCad 8.0+ (9.0 or 10.0 recommended)
  14. - `kicad-cli` in PATH (included with KiCad)
  15. ## Installation
  16. ### Recommended: Install into KiCad Python (Full PCB Analysis)
  17. 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).
  18. **Step 1**: Find your KiCad Python path:
  19. | Platform | Path |
  20. |----------|------|
  21. | Windows | `C:\Program Files\KiCad\<version>\bin\python.exe` |
  22. | macOS | `/Applications/KiCad/KiCad.app/Contents/Frameworks/python3` |
  23. | Linux | `/usr/bin/python3` (if kicad python bindings installed) |
  24. **Step 2**: Install the package into KiCad Python:
  25. ```bash
  26. # Windows example (KiCad 10.0)
  27. "C:\Program Files\KiCad\10.0\bin\python.exe" -m pip install fastmcp
  28. "C:\Program Files\KiCad\10.0\bin\python.exe" -m pip install -e .
  29. # macOS example
  30. /Applications/KiCad/KiCad.app/Contents/Frameworks/python3 -m pip install fastmcp
  31. /Applications/KiCad/KiCad.app/Contents/Frameworks/python3 -m pip install -e .
  32. ```
  33. **Step 3**: Configure MCP to use KiCad Python (see Configuration section below).
  34. ### Fallback: Install into System Python (Limited PCB Analysis)
  35. 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.
  36. ```bash
  37. pip install -e .
  38. ```
  39. ## Configuration
  40. ### Claude Desktop
  41. Edit your config file:
  42. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  43. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  44. - **Linux**: `~/.config/Claude/claude_desktop_config.json`
  45. **With KiCad Python (recommended):**
  46. ```json
  47. {
  48. "mcpServers": {
  49. "kicad": {
  50. "type": "stdio",
  51. "command": "C:\\Program Files\\KiCad\\10.0\\bin\\python.exe",
  52. "args": ["-m", "kicad_mcp_server"],
  53. "cwd": "C:\\Users\\YourName\\Desktop\\kicad-mcp-server"
  54. }
  55. }
  56. }
  57. ```
  58. **With system Python (fallback):**
  59. ```json
  60. {
  61. "mcpServers": {
  62. "kicad": {
  63. "type": "stdio",
  64. "command": "python",
  65. "args": ["-m", "kicad_mcp_server"],
  66. "cwd": "C:\\Users\\YourName\\Desktop\\kicad-mcp-server"
  67. }
  68. }
  69. }
  70. ```
  71. ### Claude Code CLI
  72. ```bash
  73. # With KiCad Python (recommended)
  74. claude mcp add kicad -s user -- "C:\Program Files\KiCad\10.0\bin\python.exe" -m kicad_mcp_server
  75. # With system Python (fallback)
  76. claude mcp add kicad -s user -- python -m kicad_mcp_server
  77. ```
  78. ### Cursor / Windsurf / Other MCP Clients
  79. Use the same config structure with your client's MCP settings. Point `command` to KiCad Python for full analysis, or `python` for fallback mode.
  80. ### Verify Installation
  81. After restarting your AI client, ask it:
  82. > "What tools are available for KiCad?"
  83. You should see a list of KiCad MCP tools. To verify pcbnew is working:
  84. > "Get PCB statistics for MyBoard.kicad_pcb"
  85. 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.
  86. Common issues:
  87. 1. KiCad is installed and `kicad-cli` is accessible
  88. 2. The `cwd` path in your config points to the correct directory
  89. 3. Python can import the package (`python -c "import kicad_mcp_server"`)
  90. ## Usage
  91. Once configured, you can interact with your KiCad projects through natural language in your AI assistant. Below are common workflows.
  92. ### 1. Analyze a Schematic
  93. Point the AI to your `.kicad_sch` file and ask questions:
  94. > "List all components in C:\Projects\MyBoard\MyBoard.kicad_sch"
  95. > "Show me all the power nets in MyBoard.kicad_sch"
  96. > "Find all resistors with value 10k"
  97. The AI will call tools like `list_schematic_components`, `list_schematic_nets`, `search_symbols` behind the scenes.
  98. ### 2. Trace Connections (Netlist-based)
  99. First export a netlist, then trace connections with pin-level accuracy:
  100. > "Generate a netlist from MyBoard.kicad_sch"
  101. > "Trace all connections from U1"
  102. > "What pins are connected to the I2C_SDA net?"
  103. This uses `generate_netlist` and `trace_netlist_connection` for 100% accurate results.
  104. ### 3. Validate Your Design
  105. Run electrical and design rule checks:
  106. > "Run ERC on MyBoard.kicad_sch and show me any errors"
  107. > "Run DRC on MyBoard.kicad_pcb"
  108. > "Are there any unconnected pins?"
  109. Uses `run_erc`, `run_drc`, and `detect_pin_conflicts`.
  110. ### 4. Analyze PCB
  111. > "Get statistics for MyBoard.kicad_pcb"
  112. > "List all footprints on the top layer"
  113. > "Find all tracks on the VDD_nRF net"
  114. > "Analyze PCB routing quality"
  115. > "Check signal integrity - are USB differential pairs length-matched?"
  116. > "Analyze power integrity - how's the GND coverage?"
  117. ### 5. Create a New Project
  118. > "Create a new KiCad project called LED_Blinker in C:\Projects"
  119. > "Add a 1k resistor called R1 to the schematic"
  120. > "Add an LED called D1"
  121. > "Add a wire from R1 pin 2 to D1 pin 1"
  122. ### 6. Pin Analysis and Code Generation
  123. > "Analyze pin functions for U1 in MyBoard.kicad_sch"
  124. > "Detect any pin conflicts in the design"
  125. > "Generate a device tree file for the STM32 on this board"
  126. > "Generate pytest hardware tests for all I2C devices"
  127. ## Available Tools Reference
  128. ### Schematic Analysis
  129. | Tool | Description |
  130. |------|-------------|
  131. | `list_schematic_components` | List components with filtering by type, value, or DNP status |
  132. | `list_schematic_nets` | List all nets, optionally filter power nets |
  133. | `get_schematic_info` | Project metadata and statistics |
  134. | `search_symbols` | Search components by pattern (regex) |
  135. | `get_symbol_details` | Detailed info for a specific component |
  136. ### PCB Analysis
  137. | Tool | Description |
  138. |------|-------------|
  139. | `list_pcb_footprints` | List footprints with optional layer filter |
  140. | `get_pcb_statistics` | Board dimensions, layer count, design rules |
  141. | `find_tracks_by_net` | Track segments, lengths, widths, vias for a specific net |
  142. | `analyze_pcb_nets` | Routing analysis: width/via distribution, net length ranking |
  143. | `analyze_pcb_signal_integrity` | Diff pair matching, RF traces, longest signal nets |
  144. | `analyze_pcb_power_integrity` | Power zones, GND coverage, power routing analysis |
  145. ### Netlist Analysis
  146. | Tool | Description |
  147. |------|-------------|
  148. | `generate_netlist` | Export netlist from schematic via kicad-cli |
  149. | `trace_netlist_connection` | Trace all connections from a component/pin |
  150. | `get_netlist_nets` | List all nets with pin connections |
  151. | `get_netlist_components` | List components with their net connections |
  152. ### Validation
  153. | Tool | Description |
  154. |------|-------------|
  155. | `run_erc` | Electrical Rules Check on schematic |
  156. | `run_drc` | Design Rules Check on PCB |
  157. | `detect_pin_conflicts` | Find conflicting pin connections |
  158. ### Editing
  159. | Tool | Description |
  160. |------|-------------|
  161. | `create_kicad_project` | Create an empty project (default) or one from a KiCad template (`template="Arduino_Uno"`) |
  162. | `add_component_from_library` | Add component with symbol from library |
  163. | `add_wire` | Add wire connection |
  164. | `add_label` | Add local label |
  165. | `setup_pcb_layout` | Initialize PCB with dimensions |
  166. | `export_gerber` | Export Gerber files |
  167. ## Editing Limitations
  168. 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.
  169. Known limitations:
  170. - Wire connections may not form perfect electrical connections
  171. - Visual alignment is basic
  172. - KiCad must be closed and reopened to see file changes (no hot-reload)
  173. **Recommendation**: Use KiCad GUI for design work. Use this MCP server for analysis, validation, and code generation.
  174. ## Troubleshooting
  175. ### "KiCad template not found" / "KiCad's Python (pcbnew) not found"
  176. Make sure KiCad is installed at the standard path:
  177. - **Windows**: `C:\Program Files\KiCad\<version>\`
  178. - **macOS**: `/Applications/KiCad/`
  179. - **Linux**: `/usr/share/kicad/`
  180. `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.
  181. ### "kicad-cli not found"
  182. Add KiCad's bin directory to your PATH:
  183. ```bash
  184. # Windows example
  185. set PATH=%PATH%;C:\Program Files\KiCad\10.0\bin
  186. # Linux/macOS example
  187. export PATH="/usr/bin:$PATH"
  188. ```
  189. ### "pcbnew module not found" / PCB analysis is limited
  190. pcbnew is only available in KiCad's bundled Python. Two options:
  191. **Option A (recommended)**: Configure MCP to use KiCad Python — see [Installation](#recommended-install-into-kicad-python-full-pcb-analysis).
  192. **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.
  193. ### Python 3.14 install fails
  194. Make sure you have `pip >= 26.0`:
  195. ```bash
  196. pip install --upgrade pip
  197. pip install -e .
  198. ```
  199. ## Resources
  200. - [KiCad Documentation](https://docs.kicad.org/)
  201. - [KiCad File Format Spec](https://dev-docs.kicad.org/en/file-formats/)
  202. - [Model Context Protocol](https://modelcontextprotocol.io/)
  203. - [kicad-cli Documentation](https://docs.kicad.org/en/cli/)
  204. ## Acknowledgments
  205. Thanks to all contributors and community feedback:
  206. - [@raffaeler](https://github.com/raffaeler) for KiCad 10 compatibility testing and feedback (#9)
  207. - [@shivam5594](https://github.com/shivam5594) for Python 3.14 install issue report (#11)
  208. - [@derekc00](https://github.com/derekc00) for lint fixes (#10)
  209. - [@befedo](https://github.com/befedo) for SchematicComponent dataclass access bug report and patch (#13)
  210. ## License
  211. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.