KiCad MCP Server

A Model Context Protocol (MCP) server for controlling KiCad EDA software — schematics, PCBs, manufacturing outputs, design checks, and library management — through any MCP-compatible AI assistant.

The server exposes 22 routers containing ~280-306 operations (the spread is because the routing router exposes 8-30 operations depending on the installed Java version). All operations return structured {ok, message, error, data} dicts.

How It Works

The server controls KiCad through three layers:

• IPC API (kicad-python / kipy): live board and project control. Requires a running KiCad GUI instance with IPC enabled (KiCad 9+). Handles reads, mutations, and interactive operations.
• kicad-cli: headless export, DRC, ERC, import, and file upgrades. No GUI needed. Handles all manufacturing output formats.
• SWIG pcbnew (legacy): direct board manipulation via KiCad's bundled Python bindings. Deprecated since KiCad 9, removed in KiCad 11. Only loads when KiCad's bundled Python is the interpreter.

A fourth layer — kicad-sch-api — provides pure-Python schematic editing with no KiCad instance required.

On Windows, the server can auto-launch KiCad as a detached background process.

Installation

From PyPI:

pip install kicad-eda-mcp
# Optional: HTTP/SSE transport (remote/multi-client)
pip install uvicorn starlette

From source (development):

pip install -e ".[dev]"

Quick Start

Any MCP client (stdio)

Add to your MCP client configuration:

{
  "mcpServers": {
    "kicad": {
      "type": "stdio",
      "command": "kicad-eda-mcp"
    }
  }
}

With mutations enabled

python -m kicad_mcp --enable-mutations

HTTP/SSE mode (multi-client)

python -m kicad_mcp --http --port 8765

Requires uvicorn and starlette (install separately — not in the default dependencies).

Progressive disclosure (context economy)

python -m kicad_mcp --tool-mode dynamic

Exposes only kicad_discover, kicad_load_toolset, kicad_unload_toolset plus the always-loaded kicad_system and kicad_calculator routers. The LLM loads additional toolsets on demand:

kicad_load_toolset(name="board")

Available Routers

Router	Ops	Backend	Purpose
kicad_system	12	CLI/IPC	Connection, version, documents, capabilities, multi-instance management
kicad_project	5	IPC	Project text variables, net classes
kicad_board	53	IPC	PCB CRUD, queries, mutations, footprint ops, layer control
kicad_board_export	27	CLI	All PCB export formats (Gerbers, PDF, SVG, STEP, drill, position, etc.)
kicad_board_check	1	CLI	Design Rule Check (DRC)
kicad_schematic	10	CLI	ERC + exports (PDF/BOM/netlist/SVG/DXF)
kicad_schematic_edit	51	kicad-sch-api	Pure-Python schematic editing (no KiCad needed)
kicad_footprint	10	CLI/git	SVG export, upgrade, parametric generation, IPC pad calc
kicad_symbol	8	CLI/git	SVG export, upgrade, STM32/AVR/connector symbol generation
kicad_gerber	3	CLI	Gerber convert/diff/info
kicad_jobset	1	CLI	Jobset execution
kicad_library	30	CLI/git	Search, KLC checks, file format editing, visual diff
kicad_swig	7	SWIG	Legacy pcbnew operations (KiCad <=10)
kicad_analysis	5	IPC/CLI	Signal/power integrity, pin analysis, routing quality, SPICE
kicad_analysis_tools	14	CLI/IPC	SI/PI/EMC calculators, design lint, pin function analysis
kicad_codegen	0	—	Device tree / test code generation (disabled stubs)
kicad_calculator	10	pure math	PCB calculators (track width, via, RF, impedance, etc.)
kicad_workflow	6	CLI	High-level composers (manufacturing package, design check, etc.)
kicad_worksheet	5	pure Python	.kicad_wks worksheet parsing and creation
kicad_routing	8-30	CLI/API	Algorithmic routing via Freerouting (Java-dependent)
kicad_quality_gates	13	CLI/IPC	Cascading quality gates, checkpoints, DRC progress
kicad_placement	5	IPC/sch-api	Force-directed PCB and schematic auto-placement

Total: 22 routers, 276 fixed operations + 8-30 routing operations (284 without Java, 306 with Java 21+).

Tool Modes and Discovery

The server supports three tool exposure modes:

Mode	Visible tools	Use case
dynamic	3 meta-tools + always-loaded routers	Context economy — LLM loads toolsets on demand
router (default)	All 22 routers	Balanced — each router is one tool with an operation parameter
full	All operations as individual tools	Future expansion (same as router for now)

Meta-tools (available in all modes)

Meta-tool	Description
kicad_discover	List all toolsets with descriptions and load status
kicad_load_toolset	Load a toolset by name (triggers background dependency check)
kicad_unload_toolset	Unload a toolset to free context space
kicad_set_profile	Switch to a pre-defined profile (see below)
kicad_get_capabilities	Report total routers, operations, dependency status
kicad_search_tools	Search all operations by keyword

Profiles

Pre-defined toolset combinations for common workflows:

Profile	Toolsets included
read-only	system, calculators, exports, analysis, libraries
minimal	system, calculators
build	system, calculators, board, schematic, schematic_edit, routing, workflow, exports, analysis
schematic_only	system, calculators, schematic, schematic_edit, libraries, workflow
pcb_only	system, calculators, board, exports, routing, analysis, workflow
manufacturing	system, calculators, exports, libraries, workflow
high_speed	system, calculators, board, analysis, routing, workflow
power	system, calculators, board, analysis, exports, workflow
simulation	system, calculators, analysis, schematic, workflow
analysis	system, calculators, analysis, board, exports, workflow
expert	All toolsets including legacy SWIG

Dependencies

Installed at pip install time (hard dependencies)

These are in pyproject.toml and installed automatically:

Package	Purpose
mcp>=1.2.0	MCP SDK (server, transport, types)
kicad-python>=0.5.0	IPC API client (kipy) for live board control
kicad-sch-api>=0.2.0	Pure-Python schematic editing
psutil>=5.9.0	Process management for auto-launch/supervisor
tabulate>=0.9.0	Required by the footprint generator for list_generators/generate_footprint

Optional dependencies

Package	Install command	Purpose
uvicorn, starlette	pip install uvicorn starlette	HTTP/SSE transport
cadquery	pip install cadquery	STEP 3D model diff and audit

The server includes a fallback self-heal mechanism (deps.py): if a hard dependency is somehow missing at runtime, it attempts a pip install in the background when the corresponding toolset is loaded. This is a safety net, not the primary install path.

Clone-on-demand library repositories

Library utility operations (KLC checks, footprint generation, symbol generation) require two GitLab repositories that are not bundled with KiCad:

• kicad-library-utils — KLC checks, file format modules, symbol generators
• kicad-footprint-generator — Parametric footprint generation

These are auto-cloned to ~/.cache/kicad-eda-mcp/ on first use and updated periodically (every 24 hours by default). Requires git in PATH.

Check status:

kicad_library → lib_status

Freerouting (algorithmic routing)

The routing router uses Freerouting, which requires Java:

• CLI pipeline (DSN export, autoroute, SES import): Java 17+
• API server pipeline (REST, sessions, jobs): Java 21+

If Java is not installed, only the 8 Java-independent routing operations (analysis, cleanup, status check) are visible. Use download_java_for_routing to auto-download a JRE from Adoptium, then restart the MCP server.

The Freerouting JAR is auto-downloaded from GitHub releases on first use.

Resources

Browsable context available without a tool call:

Resource	Description
kicad://capabilities	System capabilities and available control layers
kicad://layers	Complete list of board layer names and IDs
kicad://export-formats	All available export formats
kicad://calculators	Available PCB calculators
kicad://klc-rules	KiCad Library Convention rules (S/F/G/M categories, 84 rules)
kicad://spice-models	Built-in SPICE simulation models (opamp, varistor, potentiometer)
kicad://library-utils	Available KLC check and library management operations
kicad://quality-gates	Available quality gate operations and descriptions
kicad://subcircuit-templates	Pre-built circuit templates for rapid design

Key Operations by Category

KLC compliance checks (kicad_library)

Operation	Description
check_klc_symbol	Validate symbols against 20+ KLC rules (S3-S7, EC01-03, G1)
check_klc_footprint	Validate footprints against 18+ KLC rules (F5-F9, EC01, G1)
check_3d_coverage	Audit which footprints have 3D models
compare_libraries	Diff two library versions (added/removed/changed)
check_lib_table	Validate library table files

Footprint/symbol file editing (kicad_library)

Operation	Description
parse_footprint	Load .kicad_mod and return structure (pads, graphics, 3D models)
create_footprint	Create new footprint programmatically
edit_footprint	Modify existing footprint (name, description, tags)
parse_symbol_library	Load .kicad_sym and list symbols with properties/pins
create_symbol	Create new symbol in a library
edit_symbol	Modify existing symbol properties

Symbol generation (kicad_symbol + kicad_library)

Operation	Description
generate_symbol_from_csv	Create symbol from CSV pinout table
generate_stm32	Generate STM32 symbols from STM32CubeMX XML
generate_avr	Generate AVR DA/DB symbols from IO mux CSV
generate_connector	Generate connector symbols
generate_resistor_network	Generate resistor network symbols
generate_dip_switch	Generate DIP switch symbols

Parametric footprint generation (kicad_footprint)

Operation	Description
list_generators	List available generators (gullwing, no_lead, BGA, DIP, connectors, etc.)
generate_footprint	Generate IPC-7351 compliant footprint with 3D model
generate_batch	Batch generate multiple footprints in parallel
dry_run_generation	Preview without writing files
calc_ipc_pad	Calculate IPC-7351 pad dimensions (gullwing/nolead, 3 density levels)

Visual diff (kicad_library)

Operation	Description
visual_library_diff	Generate HTML visual diff with renders and overlays
diff_symbols	Text diff between two symbols
diff_yaml	Diff YAML generator spec files
compare_sexpr	Normalize and compare S-expression files

Quality gates (kicad_quality_gates)

Operation	Description
project_quality_gate	Top-level cascading gate: runs all sub-gates, returns PASS/FAIL/BLOCKED
schematic_quality_gate	Check schematic completeness (missing footprints, unannotated, empty values)
schematic_connectivity_gate	Check net connectivity (unconnected pins, single-pin nets)
pcb_quality_gate	Check PCB design rules via DRC
pcb_placement_quality_gate	Check placement geometry (overlaps, off-board, courtyard)
pcb_transfer_quality_gate	Check schematic-to-PCB net parity
manufacturing_quality_gate	Check manufacturing readiness (drill sizes, annular rings)
design_review_snapshot	One-call review: board info, nets, DRC, footprints, stats
project_checkpoint	Snapshot project files to a timestamped backup
project_restore_checkpoint	Restore project files from a checkpoint

Common Workflows

Export manufacturing files

kicad_workflow → export_manufacturing_package
  pcb_file: "myboard.kicad_pcb"
  output_dir: "fab/"

Run design checks

kicad_workflow → full_design_check
  sch_file: "mysch.kicad_sch"
  pcb_file: "myboard.kicad_pcb"

Calculate track width

kicad_calculator → track_width
  current_a: 2.0
  temp_rise_c: 10
  layer: "external"

Calculate IPC-7351 pad dimensions

kicad_footprint → calc_ipc_pad
  package_type: "gullwing"
  body_length: 5.0
  body_width: 4.4
  lead_width: 0.42
  density_level: "nominal"

Check KLC compliance

kicad_library → check_klc_symbol
  library_path: "mylib.kicad_sym"
  verbose: 2

kicad_library → check_klc_footprint
  footprint_paths: "SOIC-8.kicad_mod"
  verbose: 2

Generate footprint from parametric generator

kicad_footprint → generate_footprint
  generator: "package/gullwing"
  part: "SOT-23"
  output_dir: "footprints/"

Generate symbol from CSV

kicad_library → generate_symbol_from_csv
  csv_path: "pinout.csv"
  output_path: "mysym.kicad_sym"

Run the full quality gate

kicad_quality_gates → project_quality_gate
  pcb_file: "myboard.kicad_pcb"
  sch_file: "mysch.kicad_sch"

Configuration

Environment variables

Variable	Default	Description
KICAD_MCP_ENABLE_MUTATIONS	0	Enable write operations (0=read-only, 1=writes allowed)
KICAD_MCP_DRY_RUN_DEFAULT	1	Default dry_run for mutations unless explicitly overridden
KICAD_MCP_AUTO_LAUNCH	1	Auto-launch KiCad if not running
KICAD_MCP_IDLE_TTL	1800	Auto-shutdown KiCad after N seconds idle (0=never)
KICAD_MCP_SUPERVISOR_INTERVAL	60	Health-check interval for the supervisor (seconds)
KICAD_API_SOCKET	auto	Override IPC socket path
KICAD_API_TOKEN	auto	Override IPC authentication token
KICAD_MCP_CLIENT_NAME	kicad-eda-mcp	Client name reported to KiCad
KICAD_MCP_IPC_TIMEOUT_MS	60000	Timeout for IPC API requests (milliseconds)
KICAD_MCP_IPC_CONNECT_RETRIES	10	Max retries when connecting to the IPC socket
KICAD_MCP_IPC_CONNECT_DELAY	0.5	Delay between IPC connect retries (seconds)
KICAD_BIN_PATH	auto	Override KiCad executable path
KICAD_CLI_PATH	auto	Override kicad-cli path
KICAD_PYTHON_PATH	auto	Override KiCad bundled Python path (for SWIG)
KICAD_MCP_LIB_CACHE_DIR	~/.cache/kicad-eda-mcp	Cache directory for cloned library repos
KICAD_MCP_LIB_UPDATE_INTERVAL	86400	Seconds between library repo updates (0=pull every call)
KICAD_MCP_LOG_LEVEL	INFO	Logging level: DEBUG, INFO, WARNING, ERROR
KICAD_MCP_LOG_FILE	none	Log file path (default: stderr only)
KICAD_MCP_HTTP_HOST	127.0.0.1	HTTP bind host
KICAD_MCP_HTTP_PORT	8765	HTTP port
KICAD_MCP_COMMIT_PREFIX	KiCad MCP	Commit message prefix for mutation operations

CLI flags

python -m kicad_mcp [options]

  --http                Run in HTTP/SSE mode (default: stdio)
  --host HOST           HTTP bind host (default: 127.0.0.1)
  --port PORT           HTTP port (default: 8765)
  --editor-type TYPE    Scope tools to an editor: all|schematic|pcb|symbol|footprint
                        (default: all). NOTE: filtering is not yet implemented —
                        the flag is accepted but has no effect.
  --tool-mode MODE      Tool visibility: dynamic|router|full (default: router)
  --enable-mutations    Allow write operations (default: read-only)
  --auto-launch on|off  Auto-launch KiCad if not running (default: on)
  --log-level LEVEL     Logging level: DEBUG|INFO|WARNING|ERROR (default: INFO)

Requirements

• KiCad 9+ (10 recommended for full IPC API support)
• Python 3.10+
• kicad-cli in PATH (included with KiCad)
• git in PATH (for clone-on-demand library repos)
• For algorithmic routing: Java 17+ (CLI pipeline) or Java 21+ (API server)

Known Limitations

These are inherent to KiCad's version or are unimplemented features, verified against KiCad 10.0.5 and the official KiCad documentation.

Gerber tool (kicad_gerber)

KiCad's kicad-cli has no gerber or gerbview subcommand (only fp, jobset, pcb, sch, sym, version). Gerber viewing/conversion/diff is a GUI-only (GerbView) feature. The kicad_gerber router detects this and returns a clear error pointing to alternatives (GerbView GUI, gerbv, or a Python Gerber library). This is an upstream KiCad limitation, not a bug in this server.

Board PNG export

pcb export png is documented in the KiCad master branch but is absent from the installed KiCad 10.0.x CLI. The export router detects the supported-format list at runtime and returns a clear error suggesting svg or pdf instead. PNG export will work once KiCad adds the png subcommand to the CLI.

SWIG backend (kicad_swig)

The SWIG-based pcbnew Python bindings are deprecated since KiCad 9.0 and are scheduled for removal in KiCad 11. The SWIG backend only loads when KiCad's bundled Python is used as the interpreter; with a system Python (the common case), swig_pcbnew reports as unavailable. The IPC API is the supported replacement for KiCad 10+. The autoroute, panelize, and silkscreen_fix operations under kicad_swig are unimplemented stubs.

IPC API scope (KiCad 9/10)

Per the KiCad developer documentation, the IPC API in KiCad 9 and 10 supports communication with a running GUI instance only. Headless mode via kicad-cli api-server is a KiCad 11 feature. The IPC API in KiCad 9/10 has no support for plotting or exporting files from designs (also added in KiCad 11); exports are handled by the kicad-cli backend instead. There is no IPC-based autorouter or panelizer in any KiCad version.

Code generation (kicad_codegen)

The device_tree and test_code operations are unimplemented stubs. They return a descriptive message but do not parse the schematic or generate any file. Device-tree and test-scaffold generation are not KiCad features; implementing them is future work.

Editor-type filtering (--editor-type)

The --editor-type flag is accepted by the CLI but tool filtering is not yet implemented. All routers are exposed regardless of the value passed. This is reserved for future use.

Mutations

Board and project write operations (add tracks/vias/text/footprints, place footprints, commit/save) are disabled by default for safety. Set KICAD_MCP_ENABLE_MUTATIONS=1 (or pass --enable-mutations) to enable them. Every mutation supports dry_run=true to preview without writing.

Contributing

See CONTRIBUTING.md for development setup, testing, and code style guidelines.

License

MIT. See LICENSE.