KiCad MCP Server

Model Context Protocol (MCP) server for analyzing KiCad printed circuit boards. It provides a toolkit for PCB analysis, with multi-board schematic signal tracing and component datasheet lookup, exposed through a simple tool interface.

Single-board schematic text queries (component listings, per-net dumps, single-board connection tracing) have moved to the companion kicad-schema project, which renders a schematic as structured YAML. This server focuses on the analysis that is still hard to do in text form: signals that cross board boundaries, datasheet discovery, and the PCB layout surface that PCB-analysis tooling builds on.

Features

• Multi-Board Analysis: Trace signals across multiple connected boards

• Datasheet Lookup: Resolve a manufacturer and part number to a datasheet URL

• Board & System Configuration: Register boards and systems; add or remove them without restarting

• PCB Sources: Associate a .kicad_pcb layout with each board for PCB-analysis tooling

• PCB Tools (kicad-cli): Headless design-rule checking, 3D board renders, and per-layer SVG export from .kicad_pcb layouts

• Live KiCad Session: Connect to a running KiCad 9 PCB editor through the official IPC API for selection sync and reversible GUI cross-probing

• Smart Caching: Optional file caching of parsed schematics for faster repeated queries

Related MCP server: KiCad MCP Server

Installation

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e .

Requirements: Python 3.10+, and KiCad (for kicad-cli). The server discovers kicad-cli automatically at the macOS app-bundle path, /usr/bin, and on PATH; set the KICAD_CLI environment variable to point at a specific executable.

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
    pcb: /path/to/main.kicad_pcb        # optional: PCB layout for PCB-analysis tools
    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. Each board has:

  • path: path to the .kicad_sch schematic file

  • pcb (optional): path to the .kicad_pcb layout file, used by PCB-analysis tools

  • description (optional): human-readable description

• 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

Multi-Board Analysis

Datasheets

PCB Layout (kicad-cli)

These tools operate on the .kicad_pcb layout via KiCad's headless kicad-cli. The source argument accepts a configured board name (using its pcb path), a direct path to a .kicad_pcb, or a path to a .kicad_sch (resolved to its sibling .kicad_pcb).

The underlying wrappers live in kicad_mcp.kicad_cli and are importable as plain functions, so non-MCP consumers (such as a crop/highlight tool that needs board-area-fitted per-layer SVGs) can call them directly.

PCB Layout (parsed model)

These tools read a typed, in-memory model of the .kicad_pcb (placement, copper, stackup, pads, tracks, vias, zones) parsed with the pure-Python kiutils library and cached per (path, mtime) — no kicad-cli process. Their source resolves through KiCadMCPConfig.resolve_pcb_source (a configured board's pcb path, a direct .kicad_pcb path, or a .kicad_sch sibling). The queryable model lives in kicad_mcp.pcb_model; direct 2D PNG rendering lives in kicad_mcp.pcb_rendering.

Electrical estimates — IPC-2221 ampacity and IPC-2141 impedance

pcb_current_capacity and pcb_impedance_estimate are estimate tools, not thermal simulation or a field solver. They use the same pattern-first behavior as pcb_net_lengths: a glob or regular expression matches nets and returns a table across all matches. When exactly one net matches, pcb_current_capacity appends per-segment detail for each (layer, width) geometry.

pcb_current_capacity estimates each routed track geometry from copper width, stackup copper thickness, layer type, and requested temperature rise using the IPC-2221 internal or external trace current formula as appropriate for the layer. Rows sort ascending by estimated current so the weakest necks are first; min_current_a turns the table into a pass/flag check. Via barrels are estimated with IPC-2221 using a stated plating assumption.

pcb_impedance_estimate reports IPC-2141 closed-form microstrip or stripline estimates for each matched (layer, width) geometry, or for a hypothetical width_mm plus layer when iterating toward a target width. If a pattern resolves to a differential pair by the existing _P/_N or +/- conventions, it derives the same-layer spacing from route geometry and appends a coupled differential estimate.

Both tools always print assumptions. Missing stackup copper thickness defaults to 0.035 mm (1 oz), via plating defaults to 25 µm, and missing dielectric constant defaults to εr 4.4 only when the height can still be derived or is provided explicitly. For two-layer boards without stackup, impedance uses board thickness minus two 35 µm copper foils; multilayer boards without dielectric thickness refuse the affected layer with an explicit message. Nets carried by zones are flagged because the pour cross-section is not modeled, so the track neck may not be the true current limit.

Live KiCad session (IPC API)

These tools talk to a running KiCad 9 PCB editor through KiCad's official kicad-python (kipy) IPC client. They are different from the file-based PCB model tools above: they operate on the user's visible KiCad GUI session and fail closed when no IPC server is reachable. To use them, enable KiCad's API server in KiCad Preferences → Plugins, then keep the target PCB open in the PCB editor. The server attempts KiCad's default IPC socket, or KICAD_API_SOCKET when that environment variable is set, and every IPC call uses a short timeout so the MCP server does not hang.

The KiCad 9 Python IPC surface exposes open-document discovery, board item queries, selection read/write, net queries, and item-by-net queries. It does not expose a typed zoom or pan command in kicad-python 0.7.1, so live focus selects the target footprint or item and reports that view centering is unavailable rather than fabricating a GUI state.

Usage Examples

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

Datasheet Lookup

search_datasheet(
    manufacturer="Texas Instruments",
    part_number="ADS1299IPAGR"
)

Dynamic Configuration

# Add a new board, including its PCB layout
add_board(
    name="power",
    path="/path/to/power.kicad_sch",
    pcb="/path/to/power.kicad_pcb",
    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()

Development

# Install with dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Lint
uv run ruff check src/

License

MIT