KiCad MCP Server

Model Context Protocol (MCP) server for analyzing KiCad schematics. Query components, trace nets, explore connections, and analyze multi-board systems through a simple tool interface.

Features

• Circuit Analysis: Load and analyze KiCad .kicad_sch files

• Component Queries: Search, filter, and examine components with detailed pin information

• Net Tracing: Explore nets, trace signal paths, and find connection routes

• Multi-Board Systems: Analyze signals across multiple connected boards

• Smart Caching: Optional file caching for faster repeated queries

• Dynamic Configuration: Add/remove boards and systems without restarting

Installation

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e .

Requirements: Python 3.10+

Quick Start

1. Configure MCP Client

Add to your MCP client configuration (e.g., Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "kicad": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/kicad-mcp",
        "run",
        "kicad-mcp"
      ]
    }
  }
}

2. Create Configuration File

Create .kicad_mcp.yaml in your project directory:

boards:
  main:
    path: /path/to/main.kicad_sch
    description: Main controller board

  sensor:
    path: /path/to/sensor.kicad_sch
    description: Sensor board

systems:
  complete:
    boards: [main, sensor]
    description: Full system with all boards

cache:
  enabled: true
  directory: ~/.cache/kicad_mcp
  check_mtime: true

Configuration

Configuration files are searched in priority order:

1. Environment variable: $KICAD_MCP_CONFIG

2. Local project: .kicad_mcp.yaml (current directory or parent directories)

3. Global config: ~/.config/kicad_mcp/config.yaml

4. Default: Empty configuration (no boards pre-loaded)

Configuration Options

• boards: Named board configurations with paths and descriptions

• systems: Multi-board system definitions referencing board names

• cache.enabled: Enable/disable pickle caching of parsed schematics

• cache.directory: Where to store cache files

• cache.check_mtime: Invalidate cache when source files change

Available Tools

Board Management

Configuration Management

Circuit Analysis (Single Board)

Connection Tracing (Single Board)

Multi-Board Analysis

Usage Examples

Analyze a Single Board

# Get overview
get_overview(source="main")
# or use direct path:
get_overview(source="/path/to/board.kicad_sch")

# List all ICs
list_components(source="main", category="ICs")

# Examine a specific component
examine_component(source="main", reference="U1")

# Check what IC2 pin 5 connects to
check_pin_connection(source="main", reference="IC2", pin_number="5")

Trace Connections

# Find path between two components
trace_connection(source="main", start_ref="U1", end_ref="U5")

# Find everything connected to a regulator within 2 hops
find_connected_components(source="main", reference="U3", max_hops=2)

# Examine a power net
examine_net(source="main", net_name="VCC")

Multi-Board Systems

# Load and overview a system
load_system(system_name="complete")
get_system_overview(system_name="complete")

# Trace SPI signal across boards
trace_cross_board_signal(
    system_name="complete",
    signal_net="/MISO",
    start_component="main:U1",
    end_component="sensor:U2"
)

Dynamic Configuration

# Add a new board
add_board(
    name="power",
    path="/path/to/power.kicad_sch",
    description="Power supply board"
)

# Create a system with it
add_system(
    name="full_system",
    boards=["main", "sensor", "power"],
    description="Complete system with power"
)

# Reload after manual config edits
reload_config()

Source Parameter

Most analysis tools accept a source parameter which can be:

• Board name from configuration (e.g., "main")

• Direct file path to a .kicad_sch file (e.g., "/path/to/board.kicad_sch")

System tools use system_name to reference configured multi-board systems.

Development

# Install with dev dependencies
uv sync --extra dev

# Run tests
pytest

# Format code
black src/

# Type checking
mypy src/

License

MIT