AI-assisted KiCad PCB design using Model Context Protocol and Claude
Loading README and project media…
AI-assisted KiCad PCB design using Model Context Protocol (MCP) and Anthropic Claude.
This project provides an MCP server that exposes KiCad PCB design tools to AI assistants, enabling natural language interaction with your PCB designs. You can ask an AI to place components, read netlists, and get layout suggestions.
┌─────────────┐ ┌─────────────┐ ┌──────────┐
│ You │ ───────▶│ AI Client │ ───────▶│ Claude │
│ (User) │ Chat │ (Python) │ API │ AI │
└─────────────┘ └─────────────┘ └──────────┘
│
│ MCP Protocol
▼
┌─────────────┐ ┌──────────┐
│ MCP Server │ ───────▶│ KiCad │
│ (Python) │ pcbnew │ PCBNew │
└─────────────┘ └──────────┘
Works with KiCad 9.0+ Flatpak installation. This is the tested and recommended approach.
cd ~/repos
git clone https://github.com/Pablomonte/MCP-KiCad.git
cd MCP-KiCad
flatpak install flathub org.kicad.KiCad
./kicad_flatpak_setup.sh
This script automatically installs the required Python packages (mcp, anthropic, python-dotenv) inside the KiCad Flatpak container.
cp .env.example .env
nano .env # or your preferred editor
Add your Anthropic API key:
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxx
Get your API key from: https://console.anthropic.com/
Run the server using:
./run_with_flatpak.sh # Uses extended server (12 tools) by default
For native KiCad installations or development purposes.
Clone the repository and configure API key.
python3 -m venv venv
source venv/bin/activate # On Linux/Mac
# or
venv\Scripts\activate # On Windows
pip install -r requirements.txt
The MCP server needs access to KiCad's pcbnew module.
Option A: Use KiCad's Python
Find and use KiCad's Python installation:
# Linux
/usr/lib/kicad/bin/python3 kicad_mcp_server_extended.py
# Mac
/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3 kicad_mcp_server_extended.py
# Windows
"C:\Program Files\KiCad\9.0\bin\python.exe" kicad_mcp_server_extended.py
Option B: Link pcbnew to Virtual Environment
# Linux example
ln -s /usr/lib/python3/dist-packages/pcbnew.py venv/lib/python3.*/site-packages/
ln -s /usr/lib/python3/dist-packages/_pcbnew.so venv/lib/python3.*/site-packages/
Note: Exact paths vary by system. Check your KiCad installation directory.
First, open your PCB project in KiCad PCBNew:
kicad path/to/your/project.kicad_pcb
Make sure the PCB editor (PCBNew) is open, not just the project manager.
Choose between basic server (4 tools) or extended server (12 tools, recommended):
With Flatpak (Recommended):
# Extended server - recommended (includes fabrication tools)
./run_with_flatpak.sh
# Basic server only
./run_with_flatpak.sh kicad_mcp_server.py
With Native Python:
# If using virtual environment
source venv/bin/activate
python kicad_mcp_server_extended.py # or kicad_mcp_server.py for basic
# Or with KiCad's Python
/usr/lib/kicad/bin/python3 kicad_mcp_server_extended.py
The server will connect to the currently open KiCad board and wait for MCP requests.
Note: If pcbnew is not available, the server runs in mock mode for testing.
In another terminal (with virtual environment activated):
python kicad_mcp_client.py kicad_mcp_server.py
You should see:
Connected to KiCad MCP Server
Available tools: place_component, read_netlist, list_components, get_board_info
======================================================================
KiCad AI Assistant
======================================================================
You can ask me to help with your PCB design!
...
You:
Try these example queries:
Basic Operations:
You: List all components on the board
You: Place R1 at position 10, 20 mm
You: Move capacitor C1 to 15, 25 mm with 90 degree rotation
You: Show me the netlist
You: What's the board size?
You: Give me layout suggestions for an LED circuit
Fabrication Operations (Extended Server):
You: Export Gerber files to ./gerber
You: Generate drill files in Excellon format
You: Create a complete fabrication package for JLCPCB
You: Export the Bill of Materials (BOM)
You: Generate pick-and-place position file
You: Run Design Rule Check
You: Fill all copper zones
The AI will:
After the AI makes changes, refresh your KiCad view to see the updates:
F5 or use View → RefreshThe project includes two MCP server variants:
| Feature | Basic Server | Extended Server |
|---|---|---|
| Script | kicad_mcp_server.py | kicad_mcp_server_extended.py |
| Tool Count | 4 tools | 12 tools |
| Use Case | Component placement & queries | Full fabrication workflow |
| Recommended | Testing & learning | Production use |
Both servers include these basic tools:
Move a component to a specific position on the PCB.
Parameters:
reference (string): Component reference (e.g., "R1", "U1")x_mm (number): X position in millimetersy_mm (number): Y position in millimetersrotation_deg (number, optional): Rotation angle in degreesList all components on the PCB with their current positions.
Returns: JSON array of components with reference, value, position, rotation, layer
Read netlist information from the board.
Returns: JSON array of nets with names and net codes
Get general information about the PCB.
Returns: Board size, layer count, component count, filename
The extended server adds these fabrication and verification tools:
Export Gerber files (RS-274X format) for PCB manufacturing.
Parameters:
output_dir (string): Output directory pathlayers (array, optional): Specific layers to exportReturns: List of generated Gerber files
Export drill files in Excellon format.
Parameters:
output_dir (string): Output directory pathmerge_pth_npth (boolean, optional): Merge PTH and NPTH into one fileReturns: Generated drill file paths
Create a complete fabrication package as a ZIP file.
Parameters:
output_path (string): ZIP file output pathReturns: Package path and included files list
Export Bill of Materials in CSV format.
Parameters:
output_path (string): CSV file output pathinclude_dnp (boolean, optional): Include "Do Not Populate" componentsReturns: BOM file path and component count
Export component positions for pick-and-place machines.
Parameters:
output_path (string): CSV file output pathside (string, optional): "front", "back", or "both"Returns: Position file path and component count
Run Design Rule Check on the PCB.
Parameters:
report_path (string, optional): Path for DRC reportReturns: DRC status, error count, warning count
Fill copper zones on the PCB.
Parameters:
zone_names (array, optional): Specific zones to fill (default: all)Returns: Number of zones filled
Get information about tracks/traces on the PCB.
Parameters:
net_name (string, optional): Filter by net nameReturns: Track count, total length, layer distribution
JSON list of all components from the board schematic
General PCB board information and settings
Get AI-powered layout guidance for simple circuits.
Parameters:
type (string): Circuit type - "LED", "power_supply", "amplifier", etc.Returns: Layout guidelines and best practices for the specified circuit type
MCP-KiCad/
├── kicad_mcp_server.py # MCP server exposing KiCad tools
├── kicad_mcp_client.py # AI client using Claude
├── requirements.txt # Python dependencies
├── .env.example # Example environment configuration
├── .env # Your API keys (not in git)
├── .gitignore # Git ignore rules
└── README.md # This file
Via Width API Change:
get_track_info may return None for total_length_mm on boards with viasPCB_VIA::GetWidth() method signatureOptional Fields:
get_board_info fields may return None depending on board configurationNone values gracefullyTesting Status:
For detailed information, see FABRICATION.md.
The server will run in mock mode. To fix:
.env file from .env.exampleANTHROPIC_API_KEY=sk-ant-....env is in the same directory as the scriptsSymptom:
/run/build/kicad/pcbnew/pcb_track.cpp(381): assert "false" failed in GetWidth()
Explanation:
PCB_VIA::GetWidth() method signatureget_track_info operationsImpact:
get_track_info may return None for total_length_mmResolution:
Testing: Successfully tested with Olivia Control v0.2 board (38 vias) - all 12 tools functional.
For more details, see FABRICATION.md.
To use Grok instead of Claude:
kicad_mcp_client.py:# Replace Anthropic client with xAI client
from openai import OpenAI # xAI uses OpenAI-compatible API
client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1"
)
The MCP server can be used by any MCP-compatible client:
python kicad_mcp_server.py
Then connect with any MCP client using stdio transport.
Add new tools by:
list_tools() handler_route_traces())call_tool()Example tools to add:
.env file to version controlTest without KiCad by running in mock mode:
python kicad_mcp_server.py # pcbnew not available → mock mode
python kicad_mcp_client.py kicad_mcp_server.py
Mock mode returns simulated data for testing.
Add detailed logging for debugging:
import logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)
Contributions welcome! Areas for improvement:
This project is free and open source. Use it however you like.
For issues, questions, or suggestions:
Built using:
Happy PCB Designing with AI! 🤖🔌