KiCad MCP Server (IPC API)

MCP server that controls a running KiCad 9+ instance via the official IPC API and kicad-python (kipy).

Board edits appear immediately in the KiCad UI — no reload required. The server wraps the full Board + Project IPC surface available in kicad-python 0.7.1 (KiCad 10).

Prerequisites

1. KiCad 9.0+ running with a PCB open
2. IPC API enabled: Preferences → Plugins → Enable IPC API Server
3. Python 3.10+

Install

cd kicad_mcp_server_ipc
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Run

kicad-mcp-ipc
# or
python -m kicad_mcp_ipc

Cursor / Grok MCP configuration

{
  "mcpServers": {
    "kicad-ipc": {
      "command": "/path/to/kicad_mcp_server_ipc/.venv/bin/kicad-mcp-ipc"
    }
  }
}

Optional environment variables:

Variable	Description
KICAD_API_SOCKET	Path to KiCad IPC socket (auto-detected if unset)
KICAD_API_TOKEN	Auth token from KiCad when launched as plugin
KICAD_IPC_TIMEOUT_MS	Request timeout in ms (default: 5000)

Architecture

server.py              → FastMCP entry point
services/api.py        → Unified KiCadAPI facade (board + project + session)
services/export.py     → Export jobs via IPC RunJob, kicad-cli fallback
tools/definitions.py   → Tool definitions mapped to API methods
tools/registry.py      → Categories, search, JSON schemas
tools/register.py      → Dynamic MCP tool registration
layers.py / serialize.py → Layer aliases and JSON serialization

Design principles:

• Service layer — MCP tools call KiCadAPI, not kipy directly
• Registry — tool metadata (category, parameters, schema) is separate from handlers
• Transactions — edits use begin_commit / push_commit for undo support
• Meta tools — discover and invoke tools without loading all schemas upfront

Tools (77 total)

Use list_tool_categories, search_tools, or get_tool_schema to explore the full set at runtime.

Meta / discovery

Tool	Description
list_tool_categories	Browse all categories and tool names
search_tools	Search by name, description, or category
get_tool_schema	Get parameter schema for a specific tool
execute_kicad_tool	Run any tool by name with a JSON arguments object

Session (5)

ping_kicad, get_kicad_status, list_open_documents, get_kicad_version, run_kicad_action

Board query (21)

Read-only inspection: get_board_info, get_board_size, get_board_as_string, get_selection_as_string, list_components, get_component, list_tracks, list_vias, list_pads, list_nets, list_zones, list_groups, list_dimensions, list_board_text, list_board_shapes, list_barcodes, get_items_by_id, get_items_by_net, get_connected_items, get_stackup, get_title_block

Board edit (16)

save_board, revert_board, place_component, move_component, rotate_component, delete_component, route_trace, add_via, add_copper_pour, refill_zones, add_board_text, add_board_outline, add_mounting_hole, set_board_size, delete_items_by_id, set_title_block

Layers (8)

get_layer_list, get_visible_layers, get_active_layer, set_active_layer, set_visible_layers, get_copper_layer_count, set_enabled_layers, get_layer_name

Selection (4)

get_selection, add_to_selection, remove_from_selection, clear_selection

Geometry (2)

get_item_bounding_box, hit_test

Origins (2)

get_board_origin, set_board_origin

Appearance (1)

get_editor_appearance

Project (4)

get_net_classes, get_text_variables, set_text_variables, expand_text_variables

Export (10)

Manufacturing and documentation output. Each export tries the IPC RunJob API first, then falls back to kicad-cli if needed.

Tool	Output
export_gerbers	Gerber copper/silk/mask layers
export_drill	Excellon drill files
export_pdf	PDF plot
export_svg	SVG plot
export_dxf	DXF
export_3d	STEP, GLB, STL, VRML, etc.
export_position	Pick-and-place centroid files
export_ipc2581	IPC-2581 package
export_odb	ODB++ package
export_stats	Board statistics report

Response format

All tools return JSON strings:

{
  "success": true,
  "components": [...],
  "count": 42
}

On failure:

{
  "success": false,
  "message": "No PCB board is open in KiCad. Open a .kicad_pcb file first.",
  "operation": "get_board_info"
}

Limitations (kicad-python 0.7.1)

The following are not exposed because they are unavailable or unstable in the installed IPC bindings:

• Schematic editing (Schematic class exists; IPC commands not wired in 0.7.1)
• get_design_rules / import_netlist (KiCad 11+)
• set_editor_appearance_settings (read-only for safety)
• run_kicad_action (unstable KiCad internal API)

Project layout

src/kicad_mcp_ipc/
├── server.py           # MCP entry point
├── connection.py       # KiCad IPC connection singleton
├── services/
│   ├── api.py          # KiCadAPI facade
│   └── export.py       # Export via IPC jobs + kicad-cli
├── tools/
│   ├── definitions.py  # All tool definitions
│   ├── registry.py     # Category/search/schema registry
│   └── register.py     # Dynamic FastMCP registration
├── layers.py           # Layer name ↔ enum helpers
├── serialize.py        # kipy object → JSON helpers
├── board.py            # Backward-compat alias for KiCadAPI
├── errors.py
└── utils.py

License

Uses KiCad IPC via kicad-python, which is licensed under the GPL. This MCP server is a separate client application that communicates with KiCad over IPC.