KiCAD MCP Server

A production-ready Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with KiCAD for PCB design automation. Built on the MCP 2025-06-18 specification, this server provides comprehensive tool schemas and real-time project state access for intelligent PCB design workflows.

Overview

The Model Context Protocol is an open standard from Anthropic that allows AI assistants to securely connect to external tools and data sources. This implementation provides a standardized bridge between AI assistants and KiCAD, enabling natural language control of professional PCB design operations.

Key Capabilities:

52 fully-documented tools with JSON Schema validation
8 dynamic resources exposing project state
Full MCP 2025-06-18 protocol compliance
Cross-platform support (Linux, Windows, macOS)
Real-time KiCAD UI integration
Comprehensive error handling and logging

What's New in v2.1.0

Comprehensive Tool Schemas

Every tool now includes complete JSON Schema definitions with:

Detailed parameter descriptions and constraints
Input validation with type checking
Required vs. optional parameter specifications
Enumerated values for categorical inputs
Clear documentation of what each tool does

Resources Capability

Access project state without executing tools:

kicad://project/current/info - Project metadata
kicad://project/current/board - Board properties
kicad://project/current/components - Component list (JSON)
kicad://project/current/nets - Electrical nets
kicad://project/current/layers - Layer stack configuration
kicad://project/current/design-rules - Current DRC settings
kicad://project/current/drc-report - Design rule violations
kicad://board/preview.png - Board visualization (PNG)

Protocol Compliance

Updated to MCP SDK 1.21.0 (latest)
Full JSON-RPC 2.0 support
Proper capability negotiation
Standards-compliant error codes

Available Tools

The server provides 52 tools organized into functional categories:

Project Management (4 tools)

create_project - Initialize new KiCAD projects
open_project - Load existing project files
save_project - Save current project state
get_project_info - Retrieve project metadata

Board Operations (9 tools)

set_board_size - Configure PCB dimensions
add_board_outline - Create board edge (rectangle, circle, polygon)
add_layer - Add custom layers to stack
set_active_layer - Switch working layer
get_layer_list - List all board layers
get_board_info - Retrieve board properties
get_board_2d_view - Generate board preview image
add_mounting_hole - Place mounting holes
add_board_text - Add text annotations

Component Placement (10 tools)

place_component - Place single component with footprint
move_component - Reposition existing component
rotate_component - Rotate component by angle
delete_component - Remove component from board
edit_component - Modify component properties
get_component_properties - Query component details
get_component_list - List all placed components
place_component_array - Create component grids/patterns
align_components - Align multiple components
duplicate_component - Copy existing component

Routing & Nets (8 tools)

add_net - Create electrical net
route_trace - Route copper traces
add_via - Place vias for layer transitions
delete_trace - Remove traces
get_nets_list - List all nets
create_netclass - Define net class with rules
add_copper_pour - Create copper zones/pours
route_differential_pair - Route differential signals

Library Management (4 tools)

list_libraries - List available footprint libraries
search_footprints - Search for footprints
list_library_footprints - List footprints in library
get_footprint_info - Get footprint details

Design Rules (4 tools)

set_design_rules - Configure DRC parameters
get_design_rules - Retrieve current rules
run_drc - Execute design rule check
get_drc_violations - Get DRC error report

Export (5 tools)

export_gerber - Generate Gerber fabrication files
export_pdf - Export PDF documentation
export_svg - Create SVG vector graphics
export_3d - Generate 3D models (STEP/VRML)
export_bom - Produce bill of materials

Schematic Design (6 tools)

create_schematic - Initialize new schematic
load_schematic - Open existing schematic
add_schematic_component - Place symbols
add_schematic_wire - Connect component pins
list_schematic_libraries - List symbol libraries
export_schematic_pdf - Export schematic PDF

UI Management (2 tools)

check_kicad_ui - Check if KiCAD is running
launch_kicad_ui - Launch KiCAD application

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 (auto-installed):
- kicad-skip >= 0.1.0 (schematic support)
- Pillow >= 9.0.0 (image processing)
- cairosvg >= 2.7.0 (SVG rendering)
- colorlog >= 6.7.0 (logging)
- pydantic >= 2.5.0 (validation)
- requests >= 2.32.5 (HTTP client)
- python-dotenv >= 1.0.0 (environment)

MCP Client Choose one:

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

Supported Platforms

Linux (Ubuntu 22.04+, Fedora, Arch) - Primary platform, fully tested
Windows 10/11 - Fully supported with automated setup
macOS - Experimental support

Installation

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

The script will:

Detect KiCAD installation
Verify prerequisites
Install dependencies
Build project
Generate configuration
Run diagnostics

Manual Setup: See Windows Installation Guide for detailed instructions.

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.

Architecture

MCP Protocol Layer

JSON-RPC 2.0 Transport: Bi-directional communication via STDIO
Protocol Version: MCP 2025-06-18
Capabilities: Tools (52), Resources (8)
Error Handling: Standard JSON-RPC error codes

TypeScript Server (`src/`)

Implements MCP protocol specification
Manages Python subprocess lifecycle
Handles message routing and validation
Provides logging and error recovery

Python Interface (`python/`)

kicad_interface.py: Main entry point, MCP message handler
schemas/tool_schemas.py: JSON Schema definitions for all tools
resources/resource_definitions.py: Resource handlers and URIs
commands/: Modular command implementations
- project.py - Project operations
- board.py - Board manipulation
- component.py - Component placement
- routing.py - Trace routing and nets
- design_rules.py - DRC operations
- export.py - File generation
- schematic.py - Schematic design
- library.py - Footprint libraries

KiCAD Integration

pcbnew API: Direct Python bindings to KiCAD
kicad-skip: Schematic file manipulation
Platform Detection: Cross-platform path handling
UI Management: Automatic KiCAD UI launch/detection

Development

Building from Source

# Install dependencies
npm install
pip3 install -r requirements.txt

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

Running Tests

# TypeScript tests
npm run test:ts

# Python tests
npm run test:py

# All tests with coverage
npm run test:coverage

Linting and Formatting

# Lint TypeScript and Python
npm run lint

# Format code
npm run format

Troubleshooting

Server Not Appearing in Client

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

Solutions:

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

Python Module Import Errors

Symptoms: ModuleNotFoundError: No module named 'pcbnew'

Solutions:

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

Tool Execution Failures

Symptoms: Tools fail with unclear errors

Solutions:

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

Windows-Specific Issues

Symptoms: Server fails to start on Windows

Solutions:

Run automated diagnostics: .\setup-windows.ps1
Verify Python path uses double backslashes: C:\\Program Files\\KiCad\\9.0
Check Windows Event Viewer for Node.js errors
See Windows Troubleshooting Guide

Getting Help

Check the GitHub Issues
Review server logs: ~/.kicad-mcp/logs/kicad_interface.log
Open a new issue with:
- Operating system and version
- KiCAD version (python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())")
- Node.js version (node --version)
- Full error message and stack trace
- Relevant log excerpts

Project Status

Current Version: 2.1.0-alpha

Production-Ready Features:

Project creation and management
Board outline and sizing
Layer management
Component placement (with library integration needed)
Mounting holes and text annotations
Design rule checking
Export to Gerber, PDF, SVG, 3D
Schematic creation and editing
UI auto-launch
Full MCP protocol compliance

In Development:

JLCPCB parts integration
Digikey API integration
Advanced routing algorithms
Real-time UI synchronization via IPC API
Smart BOM management

Roadmap:

AI-assisted component selection
Design pattern library (Arduino shields, RPi HATs)
Interactive design review mode
Automated documentation generation
Multi-board projects

See ROADMAP.md for detailed development timeline.

Contributing

Contributions are welcome! Please follow these guidelines:

Report Bugs: Open an issue with reproduction steps
Suggest Features: Describe use case and expected behavior
Submit Pull Requests:
- Fork the repository
- Create a feature branch
- Follow existing code style
- Add tests for new functionality
- Update documentation
- Submit PR with clear description

See CONTRIBUTING.md for detailed guidelines.

License

This project is licensed under the MIT License. See LICENSE for details.

Acknowledgments

Built on the Model Context Protocol by Anthropic
Powered by KiCAD open-source PCB design software
Uses kicad-skip for schematic manipulation

Citation

If you use this project in your research or publication, please cite:

@software{kicad_mcp_server,
  title = {KiCAD MCP Server: AI-Assisted PCB Design},
  author = {mixelpixx},
  year = {2025},
  url = {https://github.com/mixelpixx/KiCAD-MCP-Server},
  version = {2.1.0-alpha}
}

KiCAD

KiCAD MCP Server

Overview

What's New in v2.1.0

Comprehensive Tool Schemas

Resources Capability

Protocol Compliance

Available Tools

Project Management (4 tools)

Board Operations (9 tools)

Component Placement (10 tools)

Routing & Nets (8 tools)

Library Management (4 tools)

Design Rules (4 tools)

Export (5 tools)

Schematic Design (6 tools)

UI Management (2 tools)

Prerequisites

Required Software

Supported Platforms

Installation

Linux (Ubuntu/Debian)

Windows 10/11

macOS

Configuration

Claude Desktop

Cline (VSCode)

Claude Code

Usage Examples

Basic PCB Design Workflow

Component Placement

Routing

Design Verification

Using Resources

Architecture

MCP Protocol Layer

TypeScript Server (src/)

Python Interface (python/)

KiCAD Integration

Development

Building from Source

Running Tests

Linting and Formatting

Troubleshooting

Server Not Appearing in Client

Python Module Import Errors

Tool Execution Failures

Windows-Specific Issues

Getting Help

Project Status

Contributing

License

Acknowledgments

Citation

Be the First to Experience Cortex App

TypeScript Server (`src/`)

Python Interface (`python/`)