KiCad MCP Pro Server

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

• Project-first workflow with kicad_set_project(), recent project discovery, and safe path handling.
• Project intent helpers with project_set_design_intent() and project_get_design_intent() for connector, decoupling, power-tree, analog/digital partitioning, sensor clustering, RF, and fab assumptions.
• KiCad 10.x-first runtime with best-effort 9.x support and cross-platform CLI/library discovery.
• PCB tools for board inspection, tracks, vias, footprints, text, shapes, outline editing, and zone refill.
• Schematic tools for symbols, wires, labels, buses, no-connect markers, property updates, annotation, netlist-aware auto-layout, and IPC reload.
• Library tools for symbol search, footprint search, datasheet lookup, footprint assignment, and custom symbol generation.
• Validation tools for DRC, ERC, DFM, courtyard issues, silk overlaps, and schematic-versus-PCB footprint checks.
• Project quality gates for schematic, schematic connectivity, PCB, placement, PCB transfer, manufacturing, and gated manufacturing handoff via export_manufacturing_package().
• Export tools for Gerber, drill, BOM, PDF, netlist, STEP, render, pick-and-place, IPC-2581, SVG, and DXF.
• Signal integrity tools for impedance synthesis, differential skew checks, stackup planning, via-stub review, and decoupling heuristics.
• Power integrity tools for voltage-drop estimation, copper current checks, plane generation, and thermal via guidance.
• EMC tools for plane coverage, return-path review, via stitching, diff-pair symmetry, and bundled compliance sweeps.
• Simulation tools for SPICE operating-point, AC, transient, DC sweep, and loop-stability checks.
• MCP resources for live board/project state, quality gates, fix queues, connectivity, and placement review.
• Prompt workflows for first-board, schematic-to-PCB, manufacturing release, design review loops, and critic/fixer iterations.
• Server profiles (full, minimal, schematic_only, pcb_only, manufacturing, high_speed, power, simulation, analysis) to reduce tool surface for clients. Legacy pcb and schematic aliases remain available.

KiCad 10 Feature Matrix

Demo

• First-board walkthrough script: docs/workflows/first-pcb.md
• KiCad Studio bridge setup: docs/integration/kicad-studio.md
• HTTP deployment notes: docs/deployment/http-mode.md

Comparison

KiCad Studio Integration

kicad-mcp-pro can run as a local HTTP bridge for the TypeScript-based kicad-studio extension. The bridge now supports:

• studio_push_context() for active file, DRC errors, selected net/reference, and cursor state.
• kicad://studio/context as a resource that agents can read directly.
• KICAD_MCP_STUDIO_WATCH_DIR for auto-project detection when .kicad_pro files change.
• /.well-known/mcp-server discovery plus bearer-token auth and CORS configuration for local-only deployments.

For Studio deployments, 27185 is a good dedicated local bridge port by convention. The server default remains 3334, so either set KICAD_MCP_PORT=27185 explicitly or keep the default and point the Studio client at that port.

CI/CD

Azure DevOps is the canonical CI/CD system for this repository. The pipeline definition lives in azure-pipelines.yml and covers linting, mypy, pytest, coverage, package builds, and optional manual publishing to TestPyPI or PyPI from Azure-managed secrets.

GitHub Actions stays in the repository only as a manual fallback surface:

• .github/workflows/ci.yml
• .github/workflows/security.yml
• .github/workflows/publish.yml

None of those workflows are intended to be the primary automated path. If GitHub-hosted automation is unavailable, queue the Azure pipeline instead and keep GitHub releases/workflows manual.

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. If you want Cursor and KiCad Studio to share the same local bridge convention, set KICAD_MCP_PORT=27185 and connect to http://127.0.0.1:27185/mcp instead.

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

• KiCad 9.0 or 10.0+ installed.
• Python 3.12+.
• For live IPC tools, KiCad must be running with the IPC API available.
• For HTTP transport, install the http extra: pip install "kicad-mcp-pro[http]".
• For FreeRouting orchestration helpers, install the freerouting extra:
  pip install "kicad-mcp-pro[freerouting]".
• For SPICE simulation tools, install the simulation extra:
  pip install "kicad-mcp-pro[simulation]".
• For Git checkpoint tools, install the vcs extra:
  pip install "kicad-mcp-pro[vcs]".

Docker Limitations

• The published container image does not bundle a KiCad installation.
• kicad-cli-backed export and validation tools require a KiCad installation inside the
  container, typically mounted at /usr/bin/kicad-cli, or KICAD_MCP_KICAD_CLI pointed to a
  valid binary.
• The default Compose setup mounts the project read-only and writes exports to
  /tmp/kicad-mcp-output. For edit/write workflows, change the project volume to rw
  intentionally and keep remote HTTP deployments behind trusted authentication and origin checks.
• Live IPC tools still require a reachable KiCad session with the IPC API enabled.

Configuration

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

• kicad_set_project
• kicad_get_project_info
• kicad_list_recent_projects
• kicad_scan_directory
• kicad_create_new_project
• kicad_get_version
• kicad_list_tool_categories
• kicad_get_tools_in_category
• kicad_help
• project_set_design_intent
• project_get_design_intent

PCB

• pcb_get_board_summary
• pcb_get_tracks (page, page_size, filter_layer, filter_net)
• pcb_get_vias
• pcb_get_footprints (page, page_size, filter_layer)
• pcb_get_nets
• pcb_get_zones
• pcb_get_shapes
• pcb_get_pads
• pcb_get_layers
• pcb_get_stackup
• pcb_get_selection
• pcb_get_board_as_string
• pcb_get_ratsnest
• pcb_get_design_rules
• pcb_get_impedance_for_trace
• pcb_check_creepage_clearance
• pcb_add_track
• pcb_add_tracks_bulk
• pcb_add_via
• pcb_add_segment
• pcb_add_circle
• pcb_add_rectangle
• pcb_add_text
• pcb_set_board_outline
• pcb_set_stackup
• pcb_add_blind_via
• pcb_add_microvia
• pcb_auto_place_by_schematic
• pcb_place_decoupling_caps
• pcb_group_by_function
• pcb_align_footprints
• pcb_set_keepout_zone
• pcb_add_mounting_holes
• pcb_add_fiducial_marks
• pcb_add_teardrops
• pcb_delete_items
• pcb_save
• pcb_refill_zones
• pcb_highlight_net
• pcb_set_net_class
• pcb_move_footprint
• pcb_set_footprint_layer
• pcb_sync_from_schematic

Schematic

• sch_get_symbols
• sch_get_wires
• sch_get_labels
• sch_get_net_names
• sch_create_sheet
• sch_list_sheets
• sch_get_sheet_info
• sch_add_symbol
• sch_add_wire
• sch_add_label
• sch_add_global_label
• sch_add_hierarchical_label
• sch_add_power_symbol
• sch_add_bus
• sch_add_bus_wire_entry
• sch_add_no_connect
• sch_update_properties
• sch_build_circuit
• sch_get_pin_positions
• sch_route_wire_between_pins
• sch_get_connectivity_graph
• sch_trace_net
• sch_auto_place_symbols
• sch_check_power_flags
• sch_annotate
• sch_reload

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

• lib_list_libraries
• lib_search_symbols
• lib_get_symbol_info
• lib_search_footprints
• lib_list_footprints
• lib_rebuild_index
• lib_get_footprint_info
• lib_get_footprint_3d_model
• lib_assign_footprint
• lib_create_custom_symbol
• lib_search_components
• lib_get_component_details
• lib_assign_lcsc_to_symbol
• lib_get_bom_with_pricing
• lib_check_stock_availability
• lib_find_alternative_parts
• lib_get_datasheet_url

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

• run_drc
• run_erc
• schematic_quality_gate
• schematic_connectivity_gate
• validate_design
• pcb_quality_gate
• pcb_placement_quality_gate
• pcb_score_placement
• manufacturing_quality_gate
• project_quality_gate
• check_design_for_manufacture
• get_unconnected_nets
• get_courtyard_violations
• get_silk_to_pad_violations
• validate_footprints_vs_schematic
• export_gerber
• export_drill
• export_bom
• export_netlist
• export_spice_netlist
• export_pcb_pdf
• export_sch_pdf
• export_3d_step
• export_step
• export_3d_render
• export_pick_and_place
• export_ipc2581
• export_svg
• export_dxf
• get_board_stats
• export_manufacturing_package

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_load_manufacturer_profile
• dfm_run_manufacturer_check
• dfm_calculate_manufacturing_cost

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

• route_single_track
• route_from_pad_to_pad
• route_export_dsn
• route_import_ses
• route_autoroute_freerouting
• route_set_net_class_rules
• route_differential_pair
• route_tune_length
• tune_track_length (deprecated alias)
• tune_diff_pair_length

Routing helpers now cover three layers:

• direct IPC routing for simple single-track and pad-to-pad paths
• rule-file authoring for net class, differential pair, and length-tuning constraints
• FreeRouting orchestration around Specctra .dsn / .ses files

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

• sim_run_operating_point
• sim_run_ac_analysis
• sim_run_transient
• sim_run_dc_sweep
• sim_check_stability
• sim_add_spice_directive

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

• si_calculate_trace_impedance
• si_calculate_trace_width_for_impedance
• si_check_differential_pair_skew
• si_validate_length_matching
• si_generate_stackup
• si_check_via_stub
• si_calculate_decoupling_placement

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

• pdn_calculate_voltage_drop
• pdn_recommend_decoupling_caps
• pdn_check_copper_weight
• pdn_generate_power_plane
• thermal_calculate_via_count
• thermal_check_copper_pour

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

• emc_check_ground_plane_voids
• emc_check_return_path_continuity
• emc_check_split_plane_crossing
• emc_check_decoupling_placement
• emc_check_via_stitching
• emc_check_differential_pair_symmetry
• emc_check_high_speed_routing_rules
• emc_run_full_compliance

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

• vcs_init_git
• vcs_commit_checkpoint
• vcs_list_checkpoints
• vcs_restore_checkpoint
• vcs_diff_with_checkpoint

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

• First PCB
• Schematic to PCB
• Manufacturing Package Export
• Azure DevOps CI/CD

The built-in MCP prompt set now also includes:

• design_review_loop
• fix_blocking_issues
• manufacturing_release_checklist

The resource surface now exposes:

• kicad://project/quality_gate
• kicad://project/fix_queue
• kicad://schematic/connectivity
• kicad://board/placement_quality

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.