kicad-mcp-server
Advanced tools
A Model Context Protocol (MCP) server for KiCad 9.x, enabling AI-assisted PCB design through Claude Code or other MCP clients.
cleanup_tasks tool for managing old async tasksLocal Machine VPS (KiCad 9.x)
┌─────────────────┐ ┌─────────────────────┐
│ Claude Code │ MCP │ MCP Server v3.5.0 │
│ or MCP Clients │◄────SSH─────►│ kicad-cli + pcbnew │
└─────────────────┘ │ + FreeRouting │
└─────────────────────┘
# Clone repository
git clone https://github.com/bunnyf/pcb-mcp.git
cd pcb-mcp
# Run install script
chmod +x scripts/install.sh
./scripts/install.sh
Or manual install:
# Install KiCad 9
sudo add-apt-repository ppa:kicad/kicad-9.0-releases -y
sudo apt update
sudo apt install kicad xvfb -y
# Install FreeRouting
sudo apt install openjdk-17-jre -y
sudo wget -q https://github.com/freerouting/freerouting/releases/download/v1.9.0/freerouting-1.9.0.jar -O /opt/freerouting.jar
# Setup MCP Server
mkdir -p /root/pcb/{mcp,projects,tasks}
cp kicad_mcp_server.py /root/pcb/mcp/
chmod +x /root/pcb/mcp/kicad_mcp_server.py
Add to your Claude Code MCP settings (~/.claude/claude_desktop_config.json):
{
"mcpServers": {
"kicad": {
"command": "ssh",
"args": [
"your-vps-host",
"python3 /root/pcb/mcp/kicad_mcp_server.py"
]
}
}
}
| Tool | Description |
|---|---|
run_drc | PCB Design Rule Check |
run_erc | Schematic Electrical Rule Check |
| Tool | Description |
|---|---|
fill_zones | Fill all copper zones |
auto_route | Auto-routing with FreeRouting (async) |
| Tool | Description |
|---|---|
get_task_status | Query async task status |
list_tasks | List all async tasks |
cleanup_tasks | Clean up old completed/failed tasks |
| Tool | Description |
|---|---|
list_projects | List all projects |
get_board_info | Board dimensions, layers, components |
get_output_files | List output files |
get_version | Version info |
| Tool | Description |
|---|---|
export_gerber | Gerber + Drill files |
export_3d | 3D render (top/bottom/iso/all) |
export_svg | PCB SVG images |
export_pdf | PCB PDF |
export_step | STEP 3D model |
| Tool | Description |
|---|---|
export_bom | Bill of Materials (CSV) |
export_netlist | Netlist (KiCad XML/SPICE) |
export_sch_pdf | Schematic PDF |
export_sch_svg | Schematic SVG |
| Tool | Description |
|---|---|
export_jlcpcb | Complete JLCPCB package |
export_all | Export all files |
| Tool | Description |
|---|---|
read_file | Read file content |
A production-ready PCB design created entirely using KiCad MCP Server + Claude Code:
See the complete example: examples/usb_nvme_adapter
User: List projects
AI: [calls list_projects]
User: Run DRC on my_board
AI: [calls run_drc with project="my_board"]
User: Generate 3D renders
AI: [calls export_3d with project="my_board", view="all"]
User: Export for JLCPCB
AI: [calls export_jlcpcb with project="my_board"]
User: Auto-route my_board
AI: [calls auto_route]
→ Returns task_id: "route_my_board_20241231_101530"
User: Check routing status
AI: [calls get_task_status with task_id]
→ {"status": "started", "log_tail": "..."}
# After completion:
AI: [calls get_task_status]
→ {"status": "completed", "message": "Auto-routing complete!"}
project/output/
├── gerber/ # Gerber + Drill files
├── bom/ # BOM CSV
├── netlist/ # Netlist files
├── 3d/ # 3D renders (PNG) + STEP model
├── images/ # SVG images
├── docs/ # PDF documents
├── reports/ # DRC/ERC reports (JSON)
├── jlcpcb/ # Complete JLCPCB package
└── backup/ # Pre-autoroute backups
Use rsync to sync projects between local and VPS:
# Upload to VPS
rsync -avz ~/pcb/my_board/ vps:/root/pcb/projects/my_board/
# Download from VPS
rsync -avz vps:/root/pcb/projects/my_board/output/ ~/pcb/my_board/output/
All server settings can be configured via environment variables. See .env.example for details.
# Base directories
KICAD_MCP_PROJECTS_BASE=/root/pcb/projects
KICAD_MCP_TASKS_DIR=/root/pcb/tasks
# External tools
KICAD_MCP_KICAD_CLI=kicad-cli
KICAD_MCP_FREEROUTING_JAR=/opt/freerouting.jar
# Timeouts (seconds)
KICAD_MCP_DEFAULT_TIMEOUT=300
KICAD_MCP_AUTOROUTE_TIMEOUT=600
# File limits
KICAD_MCP_MAX_FILE_SIZE=10485760 # 10MB
# Render settings
KICAD_MCP_RENDER_WIDTH=1920
KICAD_MCP_RENDER_HEIGHT=1080
# Task cleanup
KICAD_MCP_TASK_MAX_AGE_DAYS=7
v3.5.0 includes comprehensive security hardening:
read_file tool limited to projects/tasks directoriesshlex.quote() for all dynamic script generation# Install dev dependencies
pip3 install -r requirements.txt
# Run tests
pytest tests/ -v
# Run with coverage
pytest tests/ --cov=kicad_mcp_server --cov-report=html
# Type checking
mypy kicad_mcp_server/
# Linting
ruff check kicad_mcp_server/
GNU General Public License v3.0 or later - see LICENSE
Issues and PRs welcome!
FAQs
MCP server for AI-assisted PCB design with KiCad
We found that kicad-mcp-server demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A new federal program will let vetted U.S. cybersecurity firms help investigate and disrupt foreign cybercrime groups under government direction.
Research
/Security News
The campaign amassed more than 75,000 installs by targeting Russian-speaking users seeking access to blocked services.
Company News
Open source maintainers are under more pressure than ever. We're raising our open source program from the Team plan to the Business plan, free.