kicad-mcp-pro

KiCad MCP Pro Server

PyPI License: MIT Smithery Python 3.12+ KiCad 9+ MCP 1.6+

AI-powered PCB and schematic design with KiCad. Works with Claude, Cursor, VS Code, Claude Code, and any MCP-compatible client.

Primary CI/CD and release automation runs in Azure DevOps. GitHub Actions in this repository are manual fallback workflows only.

Features

Quick Start

Installation

Option 1: uvx (recommended)

uvx kicad-mcp-pro

Option 2: pip

pip install kicad-mcp-pro
kicad-mcp-pro

Option 3: uv

uv tool install kicad-mcp-pro

VS Code Configuration

Add this to .vscode/mcp.json:

{
  "servers": {
    "kicad": {
      "type": "stdio",
      "command": "uvx",
      "args": ["kicad-mcp-pro"],
      "env": {
        "KICAD_MCP_PROJECT_DIR": "/absolute/path/to/your/kicad-project",
        "KICAD_MCP_PROFILE": "pcb_only"
      }
    }
  }
}

Note: ${workspaceFolder} may not be expanded in some VS Code MCP setups. Use an absolute path for KICAD_MCP_PROJECT_DIR to avoid startup errors.

Codex Configuration

Add this to ~/.codex/config.toml (or project-scoped .codex/config.toml):

[mcp_servers.kicad]
command = "uvx"
args = ["kicad-mcp-pro"]
startup_timeout_sec = 20
tool_timeout_sec = 120

[mcp_servers.kicad.env]
KICAD_MCP_PROJECT_DIR = "/absolute/path/to/your/kicad-project"
KICAD_MCP_PROFILE = "pcb_only"

Claude Desktop Configuration

Add this to your Claude Desktop config:

{
  "mcpServers": {
    "kicad": {
      "command": "uvx",
      "args": ["kicad-mcp-pro"],
      "env": {
        "KICAD_MCP_PROJECT_DIR": "/path/to/your/project"
      }
    }
  }
}

VS Code / Cline

Use .vscode/mcp.json with the same server shape shown above, and keep KICAD_MCP_PROJECT_DIR as an absolute path.

Cursor

Add a custom MCP server using uvx as the command and kicad-mcp-pro as the only argument. For remote-style usage, run kicad-mcp-pro --transport http and connect to http://127.0.0.1:3334/mcp.

Claude Code

Launch the server with uvx kicad-mcp-pro, then attach it from your MCP config. The minimal profile is a good default when you mainly want read/export workflows, while pcb_only and analysis are good focused options for board-heavy sessions.

More Clients

Copy-ready configuration examples for VS Code, GitHub Copilot in VS Code, Codex, Claude Desktop, Claude Code, Cursor, Gemini CLI, Antigravity-compatible clients, and HTTP transports are available in Client Configuration.

Prerequisites

Docker Limitations

Configuration

Variable Description Default
KICAD_MCP_KICAD_CLI Path to kicad-cli Auto-detected
KICAD_MCP_NGSPICE_CLI Path to ngspice Auto-detected
KICAD_MCP_KICAD_SOCKET_PATH Optional KiCad IPC socket path Unset
KICAD_MCP_KICAD_TOKEN Optional KiCad IPC token Unset
KICAD_MCP_PROJECT_DIR Active project directory Unset
KICAD_MCP_PROJECT_FILE Explicit .kicad_pro file Auto-detected
KICAD_MCP_PCB_FILE Explicit .kicad_pcb file Auto-detected
KICAD_MCP_SCH_FILE Explicit .kicad_sch file Auto-detected
KICAD_MCP_OUTPUT_DIR Export output directory <project>/output
KICAD_MCP_SYMBOL_LIBRARY_DIR KiCad symbol library root Auto-detected
KICAD_MCP_FOOTPRINT_LIBRARY_DIR KiCad footprint library root Auto-detected
KICAD_MCP_TRANSPORT stdio, http, sse, or streamable-http stdio
KICAD_MCP_HOST HTTP bind host 127.0.0.1
KICAD_MCP_PORT HTTP bind port 3334
KICAD_MCP_MOUNT_PATH MCP HTTP mount path /mcp
KICAD_MCP_PROFILE Tool profile full
KICAD_MCP_LOG_LEVEL Log level INFO
KICAD_MCP_LOG_FORMAT console or json console
KICAD_MCP_ENABLE_EXPERIMENTAL_TOOLS Enable unstable helpers false
KICAD_MCP_IPC_CONNECTION_TIMEOUT KiCad IPC timeout in seconds 10.0
KICAD_MCP_CLI_TIMEOUT kicad-cli timeout in seconds 120.0
KICAD_MCP_MAX_ITEMS_PER_RESPONSE Max list items returned 200
KICAD_MCP_MAX_TEXT_RESPONSE_CHARS Max text payload length 50000

Preferred profile names are full, minimal, schematic_only, pcb_only, manufacturing, high_speed, power, simulation, and analysis. Legacy aliases pcb and schematic still work for older clients.

Tool Reference

Project Management

PCB

Schematic

sch_build_circuit can accept auto_layout=true for a readable grid placement. When a nets list is also provided, it performs a lightweight connection-aware layout, creates missing power symbols or labels for named nets, and generates Manhattan wire segments from symbol pins. This is a deterministic helper, not a full KiCad-quality autorouter. Multi-unit symbols such as dual op-amps can be placed and inspected with unit=<n>. The MCP now validates requested units against the KiCad library and reports available units instead of silently falling back to unit 1.

pcb_sync_from_schematic closes the first-board gap by reading schematic footprint assignments and writing missing footprint instances into the .kicad_pcb file. It is intended for initial board bring-up and footprint sync, not for full autorouting. It preserves existing footprints by default, can replace wrong footprint names in place with replace_mismatched=true, and performs a lightweight overlap-avoidance pass for newly added footprints.

v2 also adds board bring-up helpers on top of that sync path. pcb_auto_place_by_schematic can lay out the first board in cluster, linear, or star mode, while pcb_group_by_function, pcb_align_footprints, and pcb_place_decoupling_caps help refine the initial placement without opening the PCB editor. pcb_add_mounting_holes and pcb_add_fiducial_marks append simple manufacturing footprints, pcb_set_keepout_zone creates a real rule-area keepout on the active board, and pcb_add_teardrops adds small copper helper zones at basic pad-to-track junctions when the board is open over IPC. For multilayer bring-up, pcb_set_stackup stores a file-backed stackup profile and updates the board setup block so later tools can reuse the same dielectric assumptions. pcb_get_impedance_for_trace reads that active stackup and estimates impedance for a given trace width on a selected copper layer, while pcb_check_creepage_clearance performs a heuristic pad-to-pad creepage review against voltage, pollution degree, and material group. pcb_add_blind_via and pcb_add_microvia use KiCad IPC to create layer-pair vias with explicit start and end copper layers.

Library

Live component search now defaults to the zero-auth jlcsearch source. nexar and digikey remain available as authenticated source options for deployments that provide the required credentials.

Export And Validation

export_manufacturing_package is now a release-only helper. It first runs the full project_quality_gate() and hard-blocks the package when the design is still FAIL or BLOCKED. pcb_transfer_quality_gate() is part of that release contract, so schematic pad nets must transfer cleanly onto PCB pads before the gated release handoff is allowed. Use the low-level export tools for debugging or interchange artifacts while iterating; they do not enforce project_quality_gate(). The manufacturing profile keeps its export surface narrow around get_board_stats() and export_manufacturing_package(), while broader profiles such as full and minimal continue to expose the direct export_*() tools.

pcb_placement_quality_gate() is the blocking geometry/context gate. pcb_score_placement() adds softer density and spread heuristics so an agent can improve layout quality before a hard failure happens. Placement scoring is now intent-aware for connector edge usage, decoupling proximity, RF keepouts, power-tree locality, analog/digital separation, and sensor clustering.

DFM

DFM profiles are now bundled with the server for quick fabrication review. The first v2 profile set includes JLCPCB (standard, advanced), PCBWay (standard), and OSH Park (2layer). dfm_load_manufacturer_profile stores the active selection in the project output directory so later DFM checks can reuse the same fabricator assumptions.

Routing

Routing helpers now cover three layers:

Important limitation: KiCad 10 still does not expose a stable headless Specctra export/import flow through kicad-cli on all installations. route_export_dsn and route_import_ses therefore support staging existing .dsn / .ses files and explain the remaining manual KiCad PCB Editor step when needed.

Simulation

Simulation tools prefer InSpice when the simulation extra is installed and fall back to direct ngspice CLI execution when needed. sim_add_spice_directive stores a project-local sidecar file used by future MCP simulation runs, which is useful for reusable .param, .include, or .options lines.

Signal Integrity

These helpers provide fast board-level estimates for routing and review. They are intended for engineering triage and pre-layout guidance, then should be verified against your fabricator stackup and final KiCad rule setup before tape-out.

Power Integrity

These tools focus on quick PDN sanity checks: whether a rail looks too resistive, whether routed copper is undersized, whether a local plane exists, and how much thermal stitching is likely needed around hotter regions.

EMC

These EMC helpers use board-state heuristics so an agent can quickly flag likely return-path, stitching, plane, and decoupling problems before a manual SI/EMI review.

Version Control

These tools scope Git actions to the active KiCad project directory, add local identity defaults when needed, and protect restores by stashing dirty project state before rolling files back to a checkpoint commit.

Workflows

The built-in MCP prompt set now also includes:

The resource surface now exposes:

For regression coverage, the repository also ships a benchmark and failure corpus under tests/fixtures/benchmark_projects/. These fixtures are used to prove that clean projects can reach release export while known-bad projects stay hard-blocked. The corpus includes label-only schematic failures, overlap/DFM failures, bad decoupling placement, wide sensor clusters, dirty PCB transfer cases, and SismoSmart-style hierarchy/connectivity regressions.

Contributing

See CONTRIBUTING.md and the development docs in docs/development.

License

Released under the MIT License.

This site is open source. Improve this page.