KiCAD PCB Designer MCP server

The KiCAD MCP Server enables AI assistants like Claude to interact with KiCAD for PCB design automation. This server implements the Model Context Protocol (MCP), providing a standardized bridge between AI assistants and KiCAD with 52 tools, 8 dynamic resources, and experimental real-time UI integration.

Installation

Prerequisites

Required Software

KiCAD 9.0 or Higher

• Download from kicad.org/download
• Must include Python module (pcbnew)
• Verify installation:

  python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"
  

Node.js 18 or Higher

• Download from nodejs.org
• Verify: node --version and npm --version

Python 3.10 or Higher

• Usually included with KiCAD
• Required packages will be auto-installed during setup

MCP Client Choose one:

• Claude Desktop - Official Anthropic desktop app
• Claude Code - Official CLI tool
• Cline - VSCode extension

Linux (Ubuntu/Debian)

# Install KiCAD 9.0
sudo add-apt-repository --yes ppa:kicad/kicad-9.0-releases
sudo apt-get update
sudo apt-get install -y kicad kicad-libraries

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Clone and build
git clone https://github.com/mixelpixx/KiCAD-MCP-Server.git
cd KiCAD-MCP-Server
npm install
pip3 install -r requirements.txt
npm run build

# Verify
python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"

Windows 10/11

Automated Setup (Recommended):

git clone https://github.com/mixelpixx/KiCAD-MCP-Server.git
cd KiCAD-MCP-Server
.\setup-windows.ps1

macOS

# Install KiCAD 9.0 from kicad.org/download/macos

# Install Node.js
brew install node@20

# Clone and build
git clone https://github.com/mixelpixx/KiCAD-MCP-Server.git
cd KiCAD-MCP-Server
npm install
pip3 install -r requirements.txt
npm run build

Configuration

Claude Desktop

Edit configuration file:

• Linux/macOS: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "kicad": {
      "command": "node",
      "args": ["/path/to/KiCAD-MCP-Server/dist/index.js"],
      "env": {
        "PYTHONPATH": "/path/to/kicad/python",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Platform-specific PYTHONPATH:

• Linux: /usr/lib/kicad/lib/python3/dist-packages
• Windows: C:\Program Files\KiCad\9.0\lib\python3\dist-packages
• macOS: /Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages

Cline (VSCode)

Edit: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Use the same configuration format as Claude Desktop above.

Claude Code

Claude Code automatically detects MCP servers in the current directory. No additional configuration needed.

Usage Examples

Basic PCB Design Workflow

Create a new KiCAD project named 'LEDBoard' in my Documents folder.
Set the board size to 50mm x 50mm and add a rectangular outline.
Place a mounting hole at each corner, 3mm from the edges, with 3mm diameter.
Add text 'LED Controller v1.0' on the front silkscreen at position x=25mm, y=45mm.

Component Placement

Place an LED at x=10mm, y=10mm using footprint LED_SMD:LED_0805_2012Metric.
Create a grid of 4 resistors (R1-R4) starting at x=20mm, y=20mm with 5mm spacing.
Align all resistors horizontally and distribute them evenly.

Routing

Create a net named 'LED1' and route a 0.3mm trace from R1 pad 2 to LED1 anode.
Add a copper pour for GND on the bottom layer covering the entire board.
Create a differential pair for USB_P and USB_N with 0.2mm width and 0.15mm gap.

Design Verification

Set design rules with 0.15mm clearance and 0.2mm minimum track width.
Run a design rule check and show me any violations.
Export Gerber files to the 'fabrication' folder.

Using Resources

Resources provide read-only access to project state:

Show me the current component list.
What are the current design rules?
Display the board preview.
List all electrical nets.

Troubleshooting

Server Not Appearing in Client

Symptoms: MCP server doesn't show up in Claude Desktop or Cline

Solutions:

1. Verify build completed: ls dist/index.js
2. Check configuration paths are absolute
3. Restart MCP client completely
4. Check client logs for error messages

Python Module Import Errors

Symptoms: ModuleNotFoundError: No module named 'pcbnew'

Solutions:

1. Verify KiCAD installation: python3 -c "import pcbnew"
2. Check PYTHONPATH in configuration matches your KiCAD installation
3. Ensure KiCAD was installed with Python support

Tool Execution Failures

Symptoms: Tools fail with unclear errors

Solutions:

1. Check server logs: ~/.kicad-mcp/logs/kicad_interface.log
2. Verify a project is loaded before running board operations
3. Ensure file paths are absolute, not relative
4. Check tool parameter types match schema requirements

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "kicad" '{"autoApprove":[],"disabled":false,"timeout":60,"command":"C:\\Program Files\\nodejs\\node.exe","args":["C:/path/to/kicad-mcp/dist/kicad-server.js"],"env":{"PYTHONPATH":"C:/Program Files/KiCad/9.0/lib/python3/dist-packages","DEBUG":"mcp:*"},"transportType":"stdio"}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "kicad": {
            "autoApprove": [],
            "disabled": false,
            "timeout": 60,
            "command": "C:\\Program Files\\nodejs\\node.exe",
            "args": [
                "C:/path/to/kicad-mcp/dist/kicad-server.js"
            ],
            "env": {
                "PYTHONPATH": "C:/Program Files/KiCad/9.0/lib/python3/dist-packages",
                "DEBUG": "mcp:*"
            },
            "transportType": "stdio"
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "kicad": {
            "autoApprove": [],
            "disabled": false,
            "timeout": 60,
            "command": "C:\\Program Files\\nodejs\\node.exe",
            "args": [
                "C:/path/to/kicad-mcp/dist/kicad-server.js"
            ],
            "env": {
                "PYTHONPATH": "C:/Program Files/KiCad/9.0/lib/python3/dist-packages",
                "DEBUG": "mcp:*"
            },
            "transportType": "stdio"
        }
    }
}

3. Restart Claude Desktop for the changes to take effect