KiCad MCP Server

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

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:

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 .

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):

{
  "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):

{
  "mcpServers": {
    "kicad": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "kicad_mcp_server"],
      "cwd": "C:\\Users\\YourName\\Desktop\\kicad-mcp-server"
    }
  }
}

Claude Code CLI

# 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

PCB Analysis

Netlist Analysis

Validation

Editing

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"

Make sure KiCad is installed at the standard path:

• Windows: C:\Program Files\KiCad\<version>\
• macOS: /Applications/KiCad/
• Linux: /usr/share/kicad/

"kicad-cli not found"

Add KiCad's bin directory to your PATH:

# 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.

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:

pip install --upgrade pip
pip install -e .

Resources

• KiCad Documentation
• KiCad File Format Spec
• Model Context Protocol
• kicad-cli Documentation

Acknowledgments

Thanks to all contributors and community feedback:

• @raffaeler for KiCad 10 compatibility testing and feedback (#9)
• @shivam5594 for Python 3.14 install issue report (#11)
• @derekc00 for lint fixes (#10)
• @befedo for SchematicComponent dataclass access bug report and patch (#13)

License

MIT