A
licenseB
qualityD
maintenanceMCP server exposing KiCad PCB Editor functionality via IPC API.
41
47 PyPI
1
MIT
KiCad MCP Server (IPC API)
by lmaag182
Provides tools to query, edit, and manage PCB boards in a running KiCad instance, including component placement, routing, zone filling, layer control, selection, and export to various formats (Gerber, PDF, SVG, 3D, etc.).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@KiCad MCP Server (IPC API) list all components on the board"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
KiCad 9.0+ running with a PCB open
IPC API enabled: Preferences → Plugins → Enable IPC API Server
Python 3.10+
Related MCP server: KiCad MCP Server
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_ipcCursor / Grok MCP configuration
{
"mcpServers": {
"kicad-ipc": {
"command": "/path/to/kicad_mcp_server_ipc/.venv/bin/kicad-mcp-ipc"
}
}
}Optional environment variables:
Variable | Description |
| Path to KiCad IPC socket (auto-detected if unset) |
| Auth token from KiCad when launched as plugin |
| 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 serializationDesign principles:
Service layer — MCP tools call
KiCadAPI, notkipydirectlyRegistry — tool metadata (category, parameters, schema) is separate from handlers
Transactions — edits use
begin_commit/push_commitfor undo supportMeta 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 |
| Browse all categories and tool names |
| Search by name, description, or category |
| Get parameter schema for a specific 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 |
| Gerber copper/silk/mask layers |
| Excellon drill files |
| PDF plot |
| SVG plot |
| DXF |
| STEP, GLB, STL, VRML, etc. |
| Pick-and-place centroid files |
| IPC-2581 package |
| ODB++ package |
| 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.pyLicense
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.
Available Tools
77 toolsadd_board_outlineC
Add board outline segments on Edge.Cuts.
Inputs: points (required), width. Returns: result
add_board_textC
Add silkscreen or copper text.
Inputs: text (required), x (required), y (required), layer, +2 more. Returns: result
add_copper_pourC
Add a copper pour zone from polygon points.
Inputs: points (required), layer, net, clearance, +2 more. Returns: result
add_mounting_holeC
Add circular mounting hole on Edge.Cuts.
Inputs: x (required), y (required), diameter. Returns: result
add_to_selectionC
Add items to selection by UUID.
Inputs: item_ids (required). Returns: result
add_viaC
Add a through-hole via.
Inputs: x (required), y (required), size, drill, +1 more. Returns: result
clear_selectionA
Clear the editor selection.
Inputs: no named parameters. Returns: result
delete_componentB
Delete a component by reference.
Inputs: reference (required). Returns: result
delete_items_by_idC
Delete board items by UUID.
Inputs: item_ids (required). Returns: result
execute_kicad_toolC
Execute any KiCad IPC tool by name with a JSON arguments object.
Inputs: tool_name (required), arguments. Returns: result
expand_text_variablesB
Expand ${VAR} placeholders in text strings.
Inputs: texts (required). Returns: result
export_3dC
Export 3D model (STEP, GLB, STL, etc.).
Inputs: output_path (required), format_name. Returns: result
export_drillC
Export Excellon drill files.
Inputs: output_path (required). Returns: result
export_dxfC
Export board as DXF.
Inputs: output_path (required), layers. Returns: result
export_gerbersC
Export Gerber manufacturing files.
Inputs: output_path (required), layers. Returns: result
export_ipc2581C
Export IPC-2581 package.
Inputs: output_path (required). Returns: result
export_odbC
Export ODB++ package.
Inputs: output_path (required). Returns: result
export_pdfC
Export board as PDF.
Inputs: output_path (required), layers. Returns: result
export_positionC
Export pick-and-place position files.
Inputs: output_path (required), side. Returns: result
export_statsC
Export board statistics report.
Inputs: output_path (required). Returns: result
export_svgC
Export board as SVG.
Inputs: output_path (required), layers. Returns: result
get_active_layerA
Get the active drawing layer.
Inputs: no named parameters. Returns: result
get_board_as_stringA
Get the board file contents as a KiCad S-expression string.
Inputs: no named parameters. Returns: result
get_board_infoA
Get summary information about the open PCB.
Inputs: no named parameters. Returns: result
get_board_originB
Get grid or drill origin.
Inputs: origin_type. Returns: result
get_board_sizeA
Get bounding box size of the board outline in mm.
Inputs: no named parameters. Returns: result
get_componentA
Get a component by reference designator.
Inputs: reference (required). Returns: result
get_connected_itemsB
Get all copper-connected items from a starting item.
Inputs: item_id (required). Returns: result
get_copper_layer_countA
Get number of copper layers.
Inputs: no named parameters. Returns: result
get_editor_appearanceB
Get PCB editor appearance settings.
Inputs: no named parameters. Returns: result
get_item_bounding_boxC
Get bounding box for a board item.
Inputs: item_id (required), include_text. Returns: result
get_items_by_idB
Retrieve board items by their KiCad UUID.
Inputs: item_ids (required). Returns: result
get_items_by_netC
Retrieve items belonging to a net.
Inputs: net_name (required), item_types. Returns: result
get_kicad_statusA
Get KiCad connection status and version information.
Inputs: no named parameters. Returns: result
get_kicad_versionA
Get KiCad and API version details.
Inputs: no named parameters. Returns: result
get_layer_listA
List all enabled board layers.
Inputs: no named parameters. Returns: result
get_layer_nameB
Get display name for a layer.
Inputs: layer (required). Returns: result
get_net_classesA
Get project net classes.
Inputs: no named parameters. Returns: result
get_selectionA
Get currently selected board items.
Inputs: no named parameters. Returns: result
get_selection_as_stringA
Get current selection as KiCad S-expression string.
Inputs: no named parameters. Returns: result
get_stackupA
Get the board layer stackup.
Inputs: no named parameters. Returns: result
get_text_variablesB
Get project text variables.
Inputs: no named parameters. Returns: result
get_title_blockA
Get board title block fields.
Inputs: no named parameters. Returns: result
get_tool_schemaB
Get the parameter schema for a KiCad IPC tool.
Inputs: tool_name (required). Returns: result
get_visible_layersA
List layers visible in the editor.
Inputs: no named parameters. Returns: result
hit_testC
Test if a point hits a board item.
Inputs: item_id (required), x (required), y (required), tolerance_mm. Returns: result
list_barcodesB
List barcode objects on the board.
Inputs: no named parameters. Returns: result
list_board_shapesB
List graphic shapes (segments, arcs, rects, etc.).
Inputs: no named parameters. Returns: result
list_board_textA
List all board text and text boxes.
Inputs: no named parameters. Returns: result
list_componentsC
List all footprint instances on the board.
Inputs: no named parameters. Returns: result
list_dimensionsB
List all dimension objects.
Inputs: no named parameters. Returns: result
list_groupsB
List all item groups on the board.
Inputs: no named parameters. Returns: result
list_netsA
List all nets, optionally filtered by net class.
Inputs: netclass. Returns: result
list_open_documentsA
List documents currently open in KiCad.
Inputs: no named parameters. Returns: result
list_padsA
List all pads on the board.
Inputs: no named parameters. Returns: result
list_tool_categoriesB
Browse all KiCad IPC tool categories and their tools.
Inputs: no named parameters. Returns: result
list_tracksA
List all tracks and arc tracks.
Inputs: no named parameters. Returns: result
list_viasC
List all vias.
Inputs: no named parameters. Returns: result
list_zonesA
List all copper and rule zones.
Inputs: no named parameters. Returns: result
move_componentC
Move a component to a new position.
Inputs: reference (required), x (required), y (required), rotation. Returns: result
ping_kicadA
Check connectivity to the running KiCad IPC server.
Inputs: no named parameters. Returns: result
place_componentC
Place a footprint on the board.
Inputs: reference (required), footprint (required), x (required), y (required), +3 more. Returns: result
refill_zonesC
Refill all copper zones.
Inputs: block. Returns: result
remove_from_selectionB
Remove items from selection.
Inputs: item_ids (required). Returns: result
revert_boardA
Revert board to last saved state.
Inputs: no named parameters. Returns: result
rotate_componentC
Rotate a component by a relative angle.
Inputs: reference (required), angle (required). Returns: result
route_traceC
Add a copper trace between two points.
Inputs: start_x (required), start_y (required), end_x (required), end_y (required), +3 more. Returns: result
run_kicad_actionC
Run a KiCad editor action by name (unstable API).
Inputs: action (required). Returns: result
save_boardA
Save the current board, optionally to a new path.
Inputs: path. Returns: result
search_toolsB
Search KiCad IPC tools by name, description, or category.
Inputs: query (required). Returns: result
set_active_layerC
Set the active drawing layer.
Inputs: layer (required). Returns: result
set_board_originC
Set grid or drill origin.
Inputs: origin_type (required), x (required), y (required). Returns: result
set_board_sizeC
Create rectangular board outline.
Inputs: width (required), height (required). Returns: result
set_enabled_layersB
Set copper layer count and enabled non-copper layers (destructive).
Inputs: copper_layer_count (required), layers (required). Returns: result
set_text_variablesC
Set project text variables.
Inputs: variables (required). Returns: result
set_title_blockC
Update board title block fields.
Inputs: title, date, revision, company, +4 more. Returns: result
set_visible_layersC
Set which layers are visible in the editor.
Inputs: layers (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
B3.2/5.0
Scored across 77 tools
Disambiguation4/5
Most tools target distinct objects or actions, but there is potential confusion between 'execute_kicad_tool' and 'run_kicad_action', as well as among the many getter/list tools like 'get_board_info' vs 'get_board_size'. Overall, the descriptions clarify differences, keeping ambiguity low.
Naming Consistency5/5
The naming follows a consistent verb_noun pattern (e.g., add_board_outline, export_gerbers, list_nets). Minor exceptions like 'ping_kicad' and 'hit_test' are still intuitive and do not break the overall pattern.
Tool Count3/5
With 77 tools, this is a very large set for a single server. While the comprehensive PCB design domain justifies many operations, the count feels heavy and could overwhelm agents. Some tools are highly specific (e.g., refill_zones, set_board_origin), making the set borderline appropriate.
Completeness5/5
The tool set covers the full PCB design lifecycle: adding elements, editing, querying, exporting, and project management. It includes both high-level operations and detailed settings, leaving no obvious dead ends for common PCB editing tasks.
Related MCP Connectors
Design, route, check, review and export manufacturable PCBs from plain language; KiCad import.
Run ERC, DRC, parity, BOM and export checks on KiCad 9 boards before manufacturing.
Design and revise PCBs from plain language, track jobs, and retrieve design artifacts.
Headless CAD engine & MCP server for 2D/3D drafting, solids, DXF/SVG export, and automation.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables LLMs to inspect, edit, analyze, and render PCB layouts in real-time using the KiCad IPC API, providing tools for board configuration, footprints, tracks, zones, nets, text, shapes, dimensions, exports, screenshots, and CLI automation.1001MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to read and modify KiCAD PCB designs through the KiCAD IPC API, providing tools for board queries, footprint placement, track creation, DRC, and export.14MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives AI agents end-to-end control of KiCad 9+ for rule checks, manufacturing exports, production-readiness certification, and live PCB editor control.MIT