Kicad Mcp Pro

KiCad MCP Pro Server

[](https://pypi.org/project/kicad-mcp-pro/) [](LICENSE) [](https://smithery.ai/) [](pyproject.toml) [](https://www.kicad.org) [](https://github.com/oaslananka/kicad-studio) [](https://pypi.org/project/kicad-mcp-pro/) [](https://modelcontextprotocol.io/)

> 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

| Feature area | KiCad 9.x | KiCad 10.x | |---|---|---| | Core PCB + schematic inspection | Yes | Yes | | Manufacturing exports | Yes | Yes | | Variant sidecar tools (variant_*) | Best effort | Yes | | Graphical DRC rule editing (drc_rule_*) | Best effort | Yes | | Time-domain routing helpers (route_tune_time_domain) | Fallback-to-length | Yes | | 3D PDF export (pcb_export_3d_pdf) | No | Yes | | Inner-layer footprint graphics | Limited | Yes | | Design blocks + barcode helpers | Sidecar/file-based | Yes |

Demo

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

Comparison

| Capability | kicad-mcp-pro | Generic KiCad scripts | Raw kicad-cli | |---|---|---|---| | MCP tools/resources/prompts | Yes | No | No | | Project quality gates | Yes | Rare | No | | KiCad Studio local bridge | Yes | No | No | | Variant-aware workflows | Yes | Rare | No | | Streamable HTTP transport | Yes | Rare | No | | DRC/DFM/manufacturing bundle | Yes | Partial | Partial |

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](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](docs/client-configuration.md).

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

| 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 | /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

• 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=. 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-p

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Valxyria
• Source: Valxyria/kicad-mcp-pro
• License: MIT
• Homepage: https://oaslananka.github.io/kicad-mcp-pro

Install and usage instructions live in the source repository linked above.