MCP KiCad

KiCad MCP Integration

[](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://www.kicad.org/) [](https://github.com/Pablomonte/MCP-KiCad/releases/tag/v1.0.0) [](#testing) [](https://github.com/psf/black)

AI-assisted KiCad PCB design using Model Context Protocol (MCP) and Anthropic Claude.

Overview

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.

Features

• Natural Language PCB Design: Interact with KiCad using plain English
• Component Placement: Ask AI to place components at specific coordinates
• Board Analysis: Query component lists, netlists, and board information
• Layout Guidance: Get AI-powered layout suggestions for common circuit types
• Real-time Updates: Changes are immediately reflected in KiCad

Architecture

┌─────────────┐         ┌─────────────┐         ┌──────────┐
│   You       │ ───────▶│  AI Client  │ ───────▶│  Claude  │
│  (User)     │  Chat   │  (Python)   │   API   │   AI     │
└─────────────┘         └─────────────┘         └──────────┘
                              │
                              │ MCP Protocol
                              ▼
                        ┌─────────────┐         ┌──────────┐
                        │ MCP Server  │ ───────▶│  KiCad   │
                        │  (Python)   │ pcbnew  │ PCBNew   │
                        └─────────────┘         └──────────┘

Prerequisites

1. KiCad 9.0+ (Flatpak installation recommended)
2. Python 3.10+
3. Anthropic API Key (or xAI API key for Grok)

Installation

Method 1: Flatpak (Recommended)

Works with KiCad 9.0+ Flatpak installation. This is the tested and recommended approach.

Step 1: Clone the Repository

cd ~/repos
git clone https://github.com/Pablomonte/MCP-KiCad.git
cd MCP-KiCad

Step 2: Install KiCad Flatpak

flatpak install flathub org.kicad.KiCad

Step 3: Install Dependencies in Flatpak

./kicad_flatpak_setup.sh

This script automatically installs the required Python packages (mcp, anthropic, python-dotenv) inside the KiCad Flatpak container.

Step 4: Configure API Key

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/

Step 5: You're Ready!

Run the server using:

./run_with_flatpak.sh  # Uses extended server (12 tools) by default

Method 2: Native Python (Advanced)

For native KiCad installations or development purposes.

Step 1-3: Same as Flatpak Method

Clone the repository and configure API key.

Step 4: Create Virtual Environment

python3 -m venv venv
source venv/bin/activate  # On Linux/Mac
# or
venv\Scripts\activate  # On Windows

Step 5: Install Dependencies

pip install -r requirements.txt

Step 6: Setup KiCad Python Environment

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.

Usage

1. Open KiCad PCBNew

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.

2. Run the MCP Server

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.

3. Run the Client

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:

4. Interact with Your Board

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:

1. Understand your natural language request
2. Call the appropriate KiCad tools via MCP
3. Execute changes or exports on your PCB
4. Provide feedback on what was done

5. Verify Changes in KiCad

After the AI makes changes, refresh your KiCad view to see the updates:

• Click on the PCB canvas
• Press F5 or use View → Refresh

Available Tools

The project includes two MCP server variants:

Server Comparison

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

Basic Server Tools (4 tools)

Both servers include these basic tools:

place_component

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 millimeters
• y_mm (number): Y position in millimeters
• rotation_deg (number, optional): Rotation angle in degrees

list_components

List all components on the PCB with their current positions.

Returns: JSON array of components with reference, value, position, rotation, layer

read_netlist

Read netlist information from the board.

Returns: JSON array of nets with names and net codes

getboardinfo

Get general information about the PCB.

Returns: Board size, layer count, component count, filename

Extended Server Additional Tools (8 more tools)

The extended server adds these fabrication and verification tools:

Fabrication Tools (5 tools)

export_gerber

Export Gerber files (RS-274X format) for PCB manufacturing.

Parameters:

• output_dir (string): Output directory path
• layers (array, optional): Specific layers to export

Returns: List of generated Gerber files

exportdrillfiles

Export drill files in Excellon format.

Parameters:

• output_dir (string): Output directory path
• merge_pth_npth (boolean, optional): Merge PTH and NPTH into one file

Returns: Generated drill file paths

exportfabricationpackage

Create a complete fabrication package as a ZIP file.

Parameters:

• output_path (string): ZIP file output path

Returns: Package path and included files list

export_bom

Export Bill of Materials in CSV format.

Parameters:

• output_path (string): CSV file output path
• include_dnp (boolean, optional): Include "Do Not Populate" components

Returns: BOM file path and component count

exportpositionfile

Export component positions for pick-and-place machines.

Parameters:

• output_path (string): CSV file output path
• side (string, optional): "front", "back", or "both"

Returns: Position file path and component count

Verification Tools (1 tool)

run_drc

Run Design Rule Check on the PCB.

Parameters:

• report_path (string, optional): Path for DRC report

Returns: DRC status, error count, warning count

Layout Tools (2 tools)

fill_zones

Fill copper zones on the PCB.

Parameters:

• zone_names (array, optional): Specific zones to fill (default: all)

Returns: Number of zones filled

gettrackinfo

Get information about tracks/traces on the PCB.

Parameters:

• net_name (string, optional): Filter by net name

Returns: Track count, total length, layer distribution

Available Resources

board://schematic

JSON list of all components from the board schematic

board://info

General PCB board information and settings

Available Prompts

simple_circuit

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

Project Structure

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

Known Limitations

KiCad 9.x API Compatibility

Via Width API Change:

• get_track_info may return None for total_length_mm on boards with vias
• Caused by KiCad 9.x changing PCB_VIA::GetWidth() method signature
• Impact: Via length calculation may be unavailable
• Workaround: All other functionality works normally, fabrication exports unaffected

Optional Fields:

• Some get_board_info fields may return None depending on board configuration
• The server handles None values gracefully

Testing Status:

• Verified working with KiCad 9.0.5 Flatpak on real boards
• Test board: Olivia Control v0.2 (51 components, 2 layers, 56 nets, 38 vias)
• All 12 tools functional despite API warnings

For detailed information, see [FABRICATION.md](FABRICATION.md#via-width-api-change-kicad-9x).

Troubleshooting

"pcbnew module not available"

The server will run in mock mode. To fix:

• Make sure KiCad is installed
• Use KiCad's Python interpreter (see Installation step 5)
• Or link pcbnew to your virtual environment

"No PCB board is currently open in KiCad"

• Open a PCB file in KiCad PCBNew before running the server
• Make sure you're in the PCB editor, not just the project manager

"ANTHROPICAPIKEY not found"

• Create .env file from .env.example
• Add your API key: ANTHROPIC_API_KEY=sk-ant-...
• Make sure .env is in the same directory as the scripts

Component not found error

• List all components first: "List all components"
• Use exact reference designator (case-sensitive)
• Make sure components are on the PCB (not just schematic)

Changes don't appear in KiCad

• Refresh the view in KiCad (F5)
• Check the console for error messages
• Verify the server is running and connected

KiCad 9.x Via Width Warnings

Symptom:

/run/build/kicad/pcbnew/pcb_track.cpp(381): assert "false" failed in GetWidth()

Explanation:

• These warnings are expected on KiCad 9.x when processing boards with vias
• Caused by API changes in PCB_VIA::GetWidth() method signature
• Warnings appear during get_track_info operations

Impact:

• ⚠️ get_track_info may return None for total_length_mm
• ✅ All other tools work correctly
• ✅ Fabrication exports (Gerber, drill, BOM) are unaffected
• ✅ Component operations work normally

Resolution:

• No action needed - this is normal behavior on KiCad 9.x
• If you need total track length, use external tools like KiCad's built-in track length measurement
• The server handles these warnings gracefully and continues operation

Testing: Successfully tested with Olivia Control v0.2 board (38 vias) - all 12 tools functional.

For more details, see [FABRICATION.md](FABRICATION.md#testing).

Advanced Usage

Using with xAI Grok (Alternative to Claude)

To use Grok instead of Claude:

1. Get an xAI API key from https://x.ai/
2. Modify 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"
)

1. Update API calls to use xAI's model name (e.g., "grok-beta")

Running Server Standalone

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.

Extending with More Tools

Add new tools by:

1. Define tool in list_tools() handler
2. Implement tool function (e.g., _route_traces())
3. Add tool call handler in call_tool()

Example tools to add:

• Route traces between components
• Apply design rules
• Generate copper pours
• Export Gerber files
• Import component footprints

Security Considerations

• API Keys: Never commit .env file to version control
• Auto-execution: AI can modify your PCB directly - review changes carefully
• Backups: Always keep backups of your KiCad projects
• Logging: Tool calls are logged to console for transparency

Development

Testing in Mock Mode

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

Adding Logging

Add detailed logging for debugging:

import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)

Code Style

• Follow PEP 8 style guide
• Use type hints for all functions
• Document functions with docstrings
• Handle errors gracefully

Contributing

Contributions welcome! Areas for improvement:

• Support for more KiCad features (routing, DRC, etc.)
• Better error handling and recovery
• Unit tests and integration tests
• Support for other AI models
• Web-based UI
• Multi-board projects

License

This project is free and open source. Use it however you like.

Resources

• KiCad: https://www.kicad.org/
• KiCad Python API: https://docs.kicad.org/doxygen-python/namespacepcbnew.html
• MCP Protocol: https://modelcontextprotocol.io/
• Anthropic Claude: https://www.anthropic.com/
• xAI Grok: https://x.ai/

Support

For issues, questions, or suggestions:

• Check existing issues in the repository
• Read the Troubleshooting section above
• Review KiCad Python API documentation

Acknowledgments

Built using:

• KiCad Python API (pcbnew)
• Anthropic's Model Context Protocol
• Claude 3.5 Sonnet
• Python asyncio

---

Happy PCB Designing with AI! 🤖🔌

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Pablomonte
• Source: Pablomonte/MCP-KiCad
• License: MIT

Install and usage instructions live in the source repository linked above.