KiCad MCP Server

A Model Context Protocol (MCP) server for KiCad 9.x, enabling AI-assisted PCB design through Claude Code or other MCP clients.

中文文档

✨ What's New in v3.5.0

🏗️ Modular Architecture - Refactored from 987-line monolithic script to clean package structure
🔒 Security Hardening - Path validation, injection prevention, restricted file access
⚙️ Environment Configuration - All settings configurable via environment variables
🧹 Task Cleanup - New cleanup_tasks tool for managing old async tasks
✅ Unit Tests - 55 comprehensive tests covering core functionality
📝 Type Annotations - Full type hints throughout codebase
📊 Proper Logging - Structured logging framework replacing stderr prints

Features

DRC/ERC Check - Design Rule Check and Electrical Rule Check
Zone Fill - Automatic copper zone filling
Auto-routing - FreeRouting integration with async support (bypass 10-min timeout)
3D Rendering - Native KiCad 9 3D render (top/bottom/iso views)
Export - Gerber, Drill, BOM, Netlist, PDF, SVG, STEP
JLCPCB Package - Complete manufacturing files for JLCPCB/PCBWay

Architecture

Local Machine                    VPS (KiCad 9.x)
┌─────────────────┐              ┌─────────────────────┐
│  Claude Code    │     MCP      │  MCP Server v3.5.0  │
│  or MCP Clients │◄────SSH─────►│  kicad-cli + pcbnew │
└─────────────────┘              │  + FreeRouting      │
                                 └─────────────────────┘

Requirements

VPS

Ubuntu 22.04+ or Debian 12+
KiCad 9.0.6+
Python 3.10+
Java 17+ (for FreeRouting)
xvfb (for headless rendering)

Local

Claude Code with MCP support
SSH access to VPS

Quick Install

On VPS

# 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

Claude Code Configuration

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"
      ]
    }
  }
}

Available Tools (23)

Check

Tool	Description
`run_drc`	PCB Design Rule Check
`run_erc`	Schematic Electrical Rule Check

Operations

Tool	Description
`fill_zones`	Fill all copper zones
`auto_route`	Auto-routing with FreeRouting (async)

Async Tasks

Tool	Description
`get_task_status`	Query async task status
`list_tasks`	List all async tasks
`cleanup_tasks`	Clean up old completed/failed tasks

Info

Tool	Description
`list_projects`	List all projects
`get_board_info`	Board dimensions, layers, components
`get_output_files`	List output files
`get_version`	Version info

PCB Export

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

Schematic Export

Tool	Description
`export_bom`	Bill of Materials (CSV)
`export_netlist`	Netlist (KiCad XML/SPICE)
`export_sch_pdf`	Schematic PDF
`export_sch_svg`	Schematic SVG

Manufacturing

Tool	Description
`export_jlcpcb`	Complete JLCPCB package
`export_all`	Export all files

File

Tool	Description
`read_file`	Read file content

Complete Example Project

🎯 USB NVMe Adapter

A production-ready PCB design created entirely using KiCad MCP Server + Claude Code:

Design: USB-C to M.2 NVMe adapter (4-layer PCB)
Workflow: 100% AI-assisted design, no local EDA software
Components: ASM2362 bridge, TPS62913 DC-DC, USB-C connector
Outputs: Manufacturing files, 3D renders, complete documentation

See the complete example: examples/usb_nvme_adapter

3D Render

Usage Examples

Basic Workflow

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

Auto-routing (Async)

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!"}

Output Directory Structure

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

Project Sync

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/

Configuration

All server settings can be configured via environment variables. See .env.example for details.

Key Environment Variables

# 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

Security Features

v3.5.0 includes comprehensive security hardening:

Path Validation - Prevents directory traversal attacks
Restricted File Access - read_file tool limited to projects/tasks directories
Shell Injection Prevention - Uses shlex.quote() for all dynamic script generation
Input Validation - Project names sanitized to prevent path manipulation
Safe Command Execution - Proper subprocess handling with timeout protection

Development

Running Tests

# 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

Code Quality

# Type checking
mypy kicad_mcp_server/

# Linting
ruff check kicad_mcp_server/

License

GNU General Public License v3.0 or later - see LICENSE

Contributing

Issues and PRs welcome!

Acknowledgments

KiCad - Open source EDA
FreeRouting - Open source PCB auto-router
Anthropic - Claude AI and MCP protocol

kicad-mcp-server

Documentation