KiCAD MCP Server

A 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 PCB design operations.

Key Capabilities:

122 tools across 16 categories with JSON Schema validation
Smart tool discovery with router pattern (reduces AI context by 70%)
8 dynamic resources exposing project state
Complete schematic workflow with 27 tools and dynamic symbol loading (~10,000 symbols)
Freerouting autorouter integration (Java, Docker, or Podman)
Custom footprint and symbol creation tools
JLCPCB parts integration with 2.5M+ component catalog and local library search
Datasheet enrichment via LCSC
Full MCP 2025-06-18 protocol compliance
Cross-platform support (Linux, Windows, macOS)
Real-time KiCAD UI integration via IPC API (experimental)
Comprehensive error handling and logging

Try out Arduino MCP - now you can get Claude to help in the IDE, real time!:

https://github.com/mixelpixx/arduino-ide

What's New in v2.2.3

New Tools: FFC/Ribbon Cable Passthrough Workflow

A complete workflow for designing passthrough adapter boards (e.g. Raspberry Pi CSI cable adapters) is now supported:

connect_passthrough — wires all pins of one connector to the matching pins of another in the schematic (J1 pin N → J2 pin N, auto-named nets).
sync_schematic_to_board — imports the net assignments into the PCB.
route_pad_to_pad — routes each connection with automatic via insertion when pads are on opposite copper layers.
snapshot_project — saves a named checkpoint into <project>/snapshots/.

Bug Fixes (KiCAD 9 / Windows)

Via insertion for B.Cu footprints — route_pad_to_pad now correctly detects when a footprint is on B.Cu and inserts the required via. (KiCAD 9 SWIG returned F.Cu for all SMD pads regardless of layer — fixed.)
Board outline rounded corners — add_board_outline now correctly applies cornerRadius when shape="rounded_rectangle".
B.Cu placement hang — placing a footprint on B.Cu no longer causes a ~30s freeze in KiCAD 9.

Developer Mode

Set KICAD_MCP_DEV=1 in your Claude Desktop MCP environment to automatically save the MCP session log into the project's logs/ folder on every export_gerber and snapshot_project call. Useful for debugging and for attaching to GitHub issues.

"env": {
  "KICAD_MCP_DEV": "1"
}

Privacy warning: The session log contains your full tool call history (including file paths and design details). Review or delete logs/ before sharing a project directory publicly.

See CHANGELOG for the full list of changes in this release.

What's New in v2.1.0

Critical Schematic Workflow Fix + Complete Wiring System (Issue #26)

The schematic workflow was completely broken in previous versions - this is now fixed AND dramatically enhanced!

What was broken:

create_project only created PCB files, no schematics
add_schematic_component called non-existent API methods
Schematics couldn't be created or edited at all
Only 13 component types available (severe limitation)
No working wire/connection functionality

Complete Implementation (3 Phases):

Phase 1: Component Placement Foundation

create_project now creates both .kicad_pcb and .kicad_sch files
Added pre-configured template schematics with 13 common component types
Rewrote component placement to use proper clone() API

Phase 2: Dynamic Symbol Loading (BREAKTHROUGH!)

Access to ALL ~10,000 KiCad symbols from standard libraries
Automatic detection and dynamic loading from .kicad_sym library files
Zero configuration required - just specify library and symbol name
Seamless integration with existing MCP tools
Full S-expression parsing and injection system

Phase 3: Intelligent Wiring System (NEW in v2.1.0)

Automatic pin location discovery with rotation support (0°, 90°, 180°, 270°)
Smart wire routing (direct, orthogonal horizontal-first, orthogonal vertical-first)
Power symbol support (VCC, GND, +3V3, +5V, etc.)
Wire graph analysis - geometric tracing for net connectivity
Net label management (local, global, hierarchical labels)
Netlist generation with accurate component/pin connections

Technical Architecture: The kicad-skip library cannot create symbols or wires from scratch. We implemented a comprehensive solution:

Static Templates: 13 pre-configured symbols (R, C, L, LED, etc.) for instant use
Dynamic Loading: On-demand injection of ANY symbol from KiCad libraries:
- Parse .kicad_sym library files using S-expression parser
- Inject symbol definition into schematic's lib_symbols section
- Create offscreen template instance
- Reload schematic so kicad-skip sees new template
- Clone template to create actual component
Wire Creation: S-expression-based wire injection (bypasses kicad-skip API limitations)
Pin Discovery: Parse symbol definitions, apply rotation transformations, calculate absolute positions
Connectivity Analysis: Geometric wire tracing to build net connection graphs

Example - Complete Circuit Creation:

# Load power symbols dynamically
loader.load_symbol_dynamically(sch_path, "power", "VCC")

# Place components with auto-rotation
ComponentManager.add_component(sch, {
    "type": "STM32F103C8Tx",
    "library": "MCU_ST_STM32F1",
    "reference": "U1",
    "x": 100, "y": 100, "rotation": 0
})

# Connect with intelligent routing
ConnectionManager.add_connection(sch_path, "U1", "1", "R1", "2", routing="orthogonal_h")

# Connect to power nets
ConnectionManager.connect_to_net(sch_path, "U1", "VDD", "VCC")

# Analyze connectivity
connections = ConnectionManager.get_net_connections(sch, "VCC", sch_path)
# Returns: [{"component": "U1", "pin": "VDD"}, {"component": "R1", "pin": "1"}]

Test Results:

Component placement: 100% passing
Dynamic symbol loading: 10,000+ symbols accessible
Wire creation: 100% passing (8/8 connections in test circuit)
Pin discovery: Rotation-aware, sub-millimeter accuracy
Net connectivity: 100% accurate (VCC: 2 connections, GND: 4 connections)
Netlist generation: Working with accurate pin-level connections

See Schematic Tools Reference for the complete schematic tool documentation.

IPC Backend (Experimental)

We are currently implementing and testing the KiCAD 9.0 IPC API for real-time UI synchronization:

Changes made via MCP tools appear immediately in the KiCAD UI
No manual reload required when IPC is active
Hybrid backend: uses IPC when available, falls back to SWIG API
20+ commands now support IPC including routing, component placement, and zone operations

Note: IPC features are under active development and testing. Enable IPC in KiCAD via Preferences > Plugins > Enable IPC API Server.

Tool Discovery & Router Pattern

We've implemented an intelligent tool router to keep AI context efficient while maintaining full functionality:

18 direct tools always visible for high-frequency operations
65 routed tools organized into 8 categories (board, component, export, drc, schematic, library, routing, autoroute)
35 additional tools always visible (symbol/footprint creators, JLCPCB, datasheet, advanced routing)
4 router tools for discovery and execution:
- list_tool_categories - Browse all available categories
- get_category_tools - View tools in a specific category
- search_tools - Find tools by keyword
- execute_tool - Run any tool with parameters

Why this matters: By organizing tools into discoverable categories, Claude can intelligently find and use the right tool for your task without loading all 122 tool schemas into every conversation. This reduces context consumption while maintaining full access to all functionality.

Usage is seamless: Just ask naturally - "export gerber files" or "add mounting holes" - and Claude will discover and execute the appropriate tools automatically.

NEEDS TESTING - REPORT ISSUES

JLCPCB Parts Integration (New!)

Complete integration with JLCPCB's parts catalog, providing two complementary approaches for component selection:

Dual-Mode Architecture:

Local Symbol Libraries - Search JLCPCB libraries installed via KiCAD Plugin and Content Manager (contributed by @l3wi)
JLCPCB API Integration - Access the complete 2.5M+ parts catalog with real-time pricing and stock data

Key Features:

Real-time pricing with quantity breaks (1+, 10+, 100+, 1000+)
Stock availability checking
Basic vs Extended library type identification (Basic = free assembly)
Intelligent cost optimization with alternative part suggestions
Package-to-footprint mapping for KiCAD compatibility
Parametric search by category, package, manufacturer
Local SQLite database for fast offline searching
No API credentials required for local library search

Why this matters: JLCPCB offers PCB assembly services where Basic parts have no assembly fee, while Extended parts charge $3 per unique component. This integration helps you find the cheapest components with the best availability, potentially saving hundreds of dollars on assembly costs for production runs.

See JLCPCB Usage Guide for detailed setup and usage instructions.

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 122 tools organized into 16 functional categories. With the router pattern, tools are automatically discovered as needed -- just ask Claude what you want to accomplish.

For the complete tool reference with access types (direct/routed/additional), see Tool Inventory.

Project Management (5 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
snapshot_project - Save named checkpoint snapshot

Board Operations (12 tools)

set_board_size - Configure PCB dimensions
add_board_outline - Create board edge (rectangle, circle, polygon, rounded rectangle)
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
get_board_extents - Get board bounding box
add_mounting_hole - Place mounting holes
add_board_text - Add text annotations
add_zone - Add copper zone/pour with clearance settings
import_svg_logo - Import SVG file as PCB silkscreen polygons

Component Management (16 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
find_component - Search by reference or value
get_component_properties - Query component details
add_component_annotation - Add annotation/comment
group_components - Group multiple components
replace_component - Replace with different footprint
get_component_pads - Get all pad information
get_component_list - List all placed components
get_pad_position - Get precise pad position
place_component_array - Create component grids/patterns
align_components - Align multiple components
duplicate_component - Copy existing component

Routing (13 tools)

add_net - Create electrical net
route_trace - Route copper traces between XY points
route_pad_to_pad - Route between pads with auto-via insertion
add_via - Place vias for layer transitions
delete_trace - Remove traces (by UUID, position, or net)
query_traces - Query/filter traces
get_nets_list - List all nets with statistics
modify_trace - Change trace width, layer, or net
create_netclass - Define net class with rules
add_copper_pour - Create copper zones/pours
route_differential_pair - Route differential signals
refill_zones - Refill all copper zones
copy_routing_pattern - Replicate routing between component groups

Schematic (27 tools)

Complete schematic workflow with dynamic symbol loading (~10,000 symbols) and intelligent wiring.

Component Operations:

add_schematic_component - Place symbols from any KiCad library
delete_schematic_component - Remove component
edit_schematic_component - Edit properties and fields
get_schematic_component - Get component info with field positions
list_schematic_components - List all components
move_schematic_component - Reposition component
rotate_schematic_component - Rotate component
annotate_schematic - Auto-assign reference designators

Wiring and Connections:

add_wire - Create wire between points
delete_schematic_wire - Remove wire segment
add_schematic_connection - Auto-connect pins with routing
add_schematic_net_label - Add net labels (VCC, GND, signals)
delete_schematic_net_label - Remove net label
connect_to_net - Connect pin to named net
connect_passthrough - Wire all matching pins between connectors (FFC/ribbon)
get_schematic_pin_locations - Get pin locations for component

Analysis and Export:

get_net_connections - Trace net connectivity
list_schematic_nets / list_schematic_wires / list_schematic_labels
create_schematic - Create new schematic file
get_schematic_view - Rasterized schematic preview
export_schematic_svg / export_schematic_pdf
run_erc - Electrical rule check
generate_netlist - Generate netlist from schematic
sync_schematic_to_board - Import nets/pads to PCB (F8 equivalent)

See Schematic Tools Reference for details and examples.

Design Rules / DRC (8 tools)

set_design_rules / get_design_rules - Configure and inspect rules
run_drc - Execute design rule check
get_drc_violations - Get violation list by severity
add_net_class / assign_net_to_class - Net class management
set_layer_constraints / check_clearance - Layer and clearance rules

Export (8 tools)

export_gerber - Gerber fabrication files
export_pdf / export_svg - Documentation and vector graphics
export_3d - 3D models (STEP, STL, VRML, OBJ)
export_bom - Bill of materials (CSV, XML, HTML, JSON)
export_netlist - Netlist (KiCad, Spice, Cadstar, OrcadPCB2)
export_position_file - Component positions for pick and place
export_vrml - VRML 3D model

Footprint Libraries (4 tools) and Symbol Libraries (4 tools)

list_libraries / list_symbol_libraries - Browse available libraries
search_footprints / search_symbols - Search across all libraries
list_library_footprints / list_library_symbols - Browse specific library
get_footprint_info / get_symbol_info - Detailed information

Footprint Creator (4 tools) and Symbol Creator (4 tools)

Create custom components when existing libraries do not have what you need.

create_footprint / create_symbol - Build from scratch with pads/pins
edit_footprint_pad - Modify pad properties
register_footprint_library / register_symbol_library - Register in lib-table
list_footprint_libraries / list_symbols_in_library - Browse custom libraries
delete_symbol - Remove symbol from library

See Footprint and Symbol Creator Guide for details.

Datasheet Tools (2 tools)

enrich_datasheets - Auto-populate datasheet URLs using LCSC part numbers
get_datasheet_url - Get LCSC datasheet URL for a component

JLCPCB Integration (5 tools)

download_jlcpcb_database - Download 2.5M+ parts catalog (one-time setup)
search_jlcpcb_parts - Search with parametric filters
get_jlcpcb_part - Detailed part info with pricing
get_jlcpcb_database_stats - Database statistics
suggest_jlcpcb_alternatives - Find cheaper or in-stock alternatives

Freerouting Autorouter (4 tools)

autoroute - Run Freerouting autorouter (DSN export, route, SES import)
export_dsn / import_ses - Manual Specctra DSN/SES workflow
check_freerouting - Verify Java and Freerouting availability

See Freerouting Guide for setup and usage.

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-python (kipy) >= 0.5.0 (IPC API support, optional but recommended)
- 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

Important: On macOS, use KiCAD's bundled Python to ensure proper access to pcbnew module.

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

# Install Node.js
brew install node@20

# Clone repository
git clone https://github.com/mixelpixx/KiCAD-MCP-Server.git
cd KiCAD-MCP-Server

# Create virtual environment using KiCAD's bundled Python
/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3 -m venv venv --system-site-packages

# Activate virtual environment
source venv/bin/activate

# Install dependencies
npm install
pip install -r requirements.txt
npm run build

Note: The --system-site-packages flag is required to access KiCAD's pcbnew module from the virtual environment.

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

Linux Python Detection

The server automatically detects Python on Linux in this priority order:

Virtual environment - venv/bin/python or .venv/bin/python (highest priority)
KICAD_PYTHON env var - User override for non-standard installations
KiCad bundled Python - /usr/lib/kicad/bin/python3, /usr/local/lib/kicad/bin/python3, /opt/kicad/bin/python3
System Python via which - Resolves which python3 to absolute path (e.g., /usr/bin/python3)
Common system paths - /usr/bin/python3, /bin/python3

For most standard Linux installations (Ubuntu, Debian, Fedora, Arch), no KICAD_PYTHON configuration is needed - the server will automatically find your Python installation.

Troubleshooting:

If you see "Python executable not found: python3", you can manually specify the Python path:

{
  "mcpServers": {
    "kicad": {
      "command": "node",
      "args": ["/path/to/KiCAD-MCP-Server/dist/index.js"],
      "env": {
        "KICAD_PYTHON": "/usr/bin/python3",
        "PYTHONPATH": "/usr/lib/kicad/lib/python3/dist-packages"
      }
    }
  }
}

To find your Python path:

which python3  # Example output: /usr/bin/python3
python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"  # Verify pcbnew access

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.

JLCPCB Integration Setup (Optional)

The JLCPCB integration provides two modes that can be used independently or together:

Mode 1: JLCSearch Public API (Recommended - No Setup Required)

The easiest way to access JLCPCB's parts catalog:

No API credentials needed
No JLCPCB account required
Access to 2.5M+ parts with pricing and stock data
Download time: 40-60 minutes for full catalog (100-part batches due to API limit)

To download the database:

Ask Claude: "Download the JLCPCB parts database"

This creates a local SQLite database at data/jlcpcb_parts.db (3-5 GB for full 2.5M+ part catalog).

Mode 2: Local Symbol Libraries (No Setup Required)

Install JLCPCB libraries via KiCAD's Plugin and Content Manager:

Open KiCAD
Go to Tools > Plugin and Content Manager
Search for "JLCPCB" or "JLC"
Install libraries like JLCPCB-KiCAD-Library or EDA_MCP
Use search_symbols to find components with pre-configured footprints and LCSC IDs

Mode 3: Official JLCPCB API (Advanced - Requires Enterprise Account)

For users with JLCPCB enterprise accounts and order history:

Get API Credentials
- Log in to JLCPCB
- Navigate to Account > API Management (requires enterprise approval)
- Create API Key and save your appKey and appSecret
- Note: This requires prior order history and enterprise account approval

Configure Environment Variables

Add to your shell profile (~/.bashrc, ~/.zshrc, or ~/.profile):

export JLCPCB_API_KEY="your_app_key_here"
export JLCPCB_API_SECRET="your_app_secret_here"

Or create a .env file in the project root:

JLCPCB_API_KEY=your_app_key_here
JLCPCB_API_SECRET=your_app_secret_here

See JLCPCB Usage Guide for detailed documentation.

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.

Autoroute with Freerouting

Automatically route all unconnected nets using the Freerouting autorouter.

Setup (one-time):

# 1. Download the Freerouting JAR
mkdir -p ~/.kicad-mcp
curl -L -o ~/.kicad-mcp/freerouting.jar \
  https://github.com/freerouting/freerouting/releases/download/v2.0.1/freerouting-2.0.1-executable.jar

# 2. Runtime — pick ONE:
#    Option A: Docker (recommended, no Java install needed)
docker pull eclipse-temurin:21-jre

#    Option B: Install Java 21+ locally
#    (Ubuntu/Debian) sudo apt install openjdk-21-jre

The autorouter auto-detects which runtime is available (Java 21+ direct, or Docker/Podman fallback).

Check if Freerouting is ready on my system.
Autoroute the current board using Freerouting with a 5-minute timeout.

Step-by-step workflow:

1. Open the project at ~/Projects/LEDBoard/LEDBoard.kicad_pcb
2. Check Freerouting dependencies are installed
3. Run autoroute with max 10 passes
4. Run DRC to verify the autorouted result
5. Export Gerbers to the fabrication folder

Manual DSN/SES workflow (for advanced users or external autorouters):

Export the board to Specctra DSN format.
# ... run Freerouting GUI or another autorouter externally ...
Import the routed SES file from ~/Projects/LEDBoard/LEDBoard.ses

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.

JLCPCB Component Selection

Finding Components with Local Libraries:

Search for ESP32 modules in JLCPCB libraries.
Find a 10k resistor in 0603 package from installed libraries.
Show me details for LCSC part C2934196.

Optimizing Costs with JLCPCB API:

Search for 10k ohm resistors in 0603 package, only Basic parts.
Find the cheapest capacitor 10uF 25V in 0805 package with good stock.
Show me pricing and stock for JLCPCB part C25804.
Suggest cheaper alternatives to C25804.

Complete Design Workflow:

I'm designing a board with an ESP32 and need to select components for JLCPCB assembly.
Search JLCPCB for ESP32-C3 modules.
Find Basic parts for: 10k resistor 0603, 100nF capacitor 0603, LED 0805.
For each component, show me the cheapest option with good stock availability.
Place these components on my board using the suggested footprints.

Database Management:

Download the JLCPCB parts database (first time setup).
Show me JLCPCB database statistics.
How many Basic parts are available?

Architecture

MCP Protocol Layer

JSON-RPC 2.0 Transport: Bi-directional communication via STDIO
Protocol Version: MCP 2025-06-18
Capabilities: Tools (122), Resources (8)
Tool Router: Intelligent discovery system with 8 categories
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
Router System:
- src/tools/registry.ts - Tool categorization and lookup
- src/tools/router.ts - Discovery and execution tools
- Reduces AI context usage by 70% while maintaining full functionality

Python Interface (`python/`)

kicad_interface.py: Main entry point, MCP message handler, command routing
kicad_api/: Backend implementations
- base.py - Abstract base classes for backends
- ipc_backend.py - KiCAD 9.0 IPC API backend (real-time UI sync)
- swig_backend.py - pcbnew SWIG API backend (file-based operations)
- factory.py - Backend auto-detection and instantiation
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
- library_symbol.py - Symbol library search (local JLCPCB libraries)
- jlcpcb.py - JLCPCB API client
- jlcpcb_parts.py - JLCPCB parts database manager

KiCAD Integration

pcbnew API (SWIG): Direct Python bindings to KiCAD for file operations
IPC API (kipy): Real-time communication with running KiCAD instance (experimental)
Hybrid Backend: Automatically uses IPC when available, falls back to SWIG
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.2.3

See STATUS_SUMMARY.md for the complete status matrix and CHANGELOG.md for detailed release notes.

Working Features (122 tools):

Project management with snapshot checkpointing
Complete board design (outline, layers, zones, mounting holes, text, SVG logos)
Component placement with arrays, alignment, and duplication
Advanced routing (pad-to-pad with auto-via, differential pairs, pattern copying)
Complete schematic workflow with dynamic symbol loading (~10,000 symbols)
Intelligent wiring system with pin discovery and smart routing
FFC/ribbon cable passthrough workflow
Schematic-to-board synchronization
Design rule checking (DRC and ERC)
Export to Gerber, PDF, SVG, 3D, BOM, netlist, position file
Custom footprint and symbol creation
JLCPCB parts integration (2.5M+ parts catalog)
Datasheet enrichment via LCSC
Freerouting autorouter integration (Java, Docker, Podman)
UI auto-launch and management
Full MCP 2025-06-18 protocol compliance

IPC Backend (Experimental):

Real-time UI synchronization via KiCAD 9.0 IPC API
21 IPC-enabled commands with automatic SWIG fallback
Hybrid footprint loading (SWIG for library access, IPC for placement)

Developer Mode: Set KICAD_MCP_DEV=1 to capture MCP session logs for debugging. See CHANGELOG v2.2.3 for details.

See ROADMAP.md for planned features.

What Do You Want to See Next?

We are actively developing new features. Your feedback directly shapes development priorities.

Share your ideas:

Open a feature request
Join the discussion
Star the repo if you find it useful

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
JLCSearch API by @tscircuit - Public JLCPCB parts API
JLCParts Database by @yaqwsx - JLCPCB parts data

Community Contributors

@Kletternaut - Routing/component tools, footprint/symbol creators, passthrough workflow, template fixes (PRs #44, #48, #49, #51, #53, #57, #59)
@Mehanik - Schematic inspection/editing tools, component field positions (PRs #60, #66, #67)
@jflaflamme - Freerouting autorouter integration with Docker/Podman support (PR #68)
@l3wi - Local symbol library search, JLCPCB third-party library support (PR #25)
@gwall-ceres - MCP protocol compliance, Windows compatibility (PR #10)
@fariouche - Bug fixes (PR #17)
@shuofengzhang - XDG relative path handling (PR #58)
@sid115 - Windows setup script improvements (PR #13)
@pasrom - MCP server bug fixes (PR #50)

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.2.3}
}

Name		Name	Last commit message	Last commit date
Latest commit History 169 Commits
.github/workflows		.github/workflows
config		config
docs		docs
python		python
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
pytest.ini		pytest.ini
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
setup-windows.ps1		setup-windows.ps1
test-router.js		test-router.js
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

KiCAD MCP Server

Overview

Try out Arduino MCP - now you can get Claude to help in the IDE, real time!:

What's New in v2.2.3

New Tools: FFC/Ribbon Cable Passthrough Workflow

Bug Fixes (KiCAD 9 / Windows)

Developer Mode

What's New in v2.1.0

Critical Schematic Workflow Fix + Complete Wiring System (Issue #26)

IPC Backend (Experimental)

Tool Discovery & Router Pattern

NEEDS TESTING - REPORT ISSUES

JLCPCB Parts Integration (New!)

Comprehensive Tool Schemas

Resources Capability

Protocol Compliance

Available Tools

Project Management (5 tools)

Board Operations (12 tools)

Component Management (16 tools)

Routing (13 tools)

Schematic (27 tools)

Design Rules / DRC (8 tools)

Export (8 tools)

Footprint Libraries (4 tools) and Symbol Libraries (4 tools)

Footprint Creator (4 tools) and Symbol Creator (4 tools)

Datasheet Tools (2 tools)

JLCPCB Integration (5 tools)

Freerouting Autorouter (4 tools)

UI Management (2 tools)

Prerequisites

Required Software

Supported Platforms

Installation

Linux (Ubuntu/Debian)

Windows 10/11

macOS

Configuration

Claude Desktop

Linux Python Detection

Cline (VSCode)

Claude Code

JLCPCB Integration Setup (Optional)

Usage Examples

Basic PCB Design Workflow

Component Placement

Routing

Autoroute with Freerouting

Design Verification

Using Resources

JLCPCB Component Selection

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

What Do You Want to See Next?

Contributing

License

Acknowledgments

Community Contributors

Citation

About

Resources

License

TypeScript Server (`src/`)

Python Interface (`python/`)

Packages