9.7 KiB
KiCAD IPC Backend Implementation Status
Status: Under Active Development and Testing Date: 2026-03-21 KiCAD Version: 9.0+ kicad-python Version: 0.5.0+
Overview
The IPC backend provides real-time UI synchronization with KiCAD 9.0+ via the official IPC API. When KiCAD is running with IPC enabled, commands can update the KiCAD UI immediately without requiring manual reload.
This feature is experimental and under active testing. The server uses a hybrid approach: IPC when available, automatic fallback to SWIG when IPC is not connected, and runtime reconnect when KiCAD becomes available after the MCP server has already started. Tools with IPC implementations recheck IPC availability at runtime and reconnect if KiCAD is available, which prevents the MCP from staying in SWIG for the entire session after an initial failure to connect to IPC.
Key Differences
| Feature | SWIG | IPC |
|---|---|---|
| UI Updates | Manual reload required | Immediate (when working) |
| Undo/Redo | Not supported | Transaction support |
| API Stability | Deprecated in KiCAD 9 | Official, versioned |
| Connection | File-based | Live socket connection |
| KiCAD Required | No (file operations) | Yes (must be running) |
Implemented IPC Commands
The following MCP commands have IPC handlers:
| Command | IPC Handler | Status |
|---|---|---|
route_trace |
_ipc_route_trace |
Implemented |
add_via |
_ipc_add_via |
Implemented |
add_net |
_ipc_add_net |
Implemented |
delete_trace |
_ipc_delete_trace |
Falls back to SWIG |
query_traces |
_ipc_query_traces |
Implemented |
get_nets_list |
_ipc_get_nets_list |
Implemented |
add_copper_pour |
_ipc_add_copper_pour |
Implemented |
refill_zones |
_ipc_refill_zones |
Implemented |
add_text |
_ipc_add_text |
Implemented |
add_board_text |
_ipc_add_text |
Implemented |
set_board_size |
_ipc_set_board_size |
Implemented |
get_board_info |
_ipc_get_board_info |
Implemented |
add_board_outline |
_ipc_add_board_outline |
Implemented |
add_mounting_hole |
_ipc_add_mounting_hole |
Implemented |
get_layer_list |
_ipc_get_layer_list |
Implemented |
place_component |
_ipc_place_component |
Implemented (hybrid) |
move_component |
_ipc_move_component |
Implemented |
rotate_component |
_ipc_rotate_component |
Implemented |
delete_component |
_ipc_delete_component |
Implemented |
get_component_list |
_ipc_get_component_list |
Implemented |
get_component_properties |
_ipc_get_component_properties |
Implemented |
save_project |
_ipc_save_project |
Implemented |
Implemented Backend Features
Core Connection:
- Connect to running KiCAD instance
- Auto-detect socket path (
/tmp/kicad/api.sock) - Version checking and validation
- Auto-fallback to SWIG when IPC unavailable
- Runtime reconnect from SWIG to IPC when KiCAD starts after MCP
- Change notification callbacks
Board Operations:
- Get board reference
- Get/Set board size
- List enabled layers
- Save board
- Add board outline segments
- Add mounting holes
Component Operations:
- List all components
- Place component (hybrid: SWIG for library loading, IPC for placement)
- Move component
- Rotate component
- Delete component
- Get component properties
Routing Operations:
- Add track
- Add via
- Get all tracks
- Get all vias
- Get all nets
- Query traces from the live board with net, layer, and bounding-box filters
Zone Operations:
- Add copper pour zones
- Get zones list
- Refill zones
UI Integration:
- Add text to board
- Get current selection
- Clear selection
Transaction Support:
- Begin transaction
- Commit transaction (with description for undo)
- Rollback transaction
Usage
Prerequisites
- KiCAD 9.0+ must be running
- IPC API must be enabled:
Preferences > Plugins > Enable IPC API Server - A board must be open in the PCB editor
Installation
pip install kicad-python
Runtime Backend Selection
At startup, the server attempts IPC first when KICAD_BACKEND is auto or
ipc. If KiCAD is not running yet, auto mode falls back to SWIG so file-based
operations can still work.
IPC-capable board tools now retry the IPC connection at runtime. This means the following workflow can switch from SWIG to IPC without restarting the MCP server:
- Start the MCP server before KiCAD is running.
- Launch KiCAD manually or with
launch_kicad_ui. - Open a board with IPC enabled in KiCAD.
- Call a normal IPC-capable board tool such as
get_board_info,get_layer_list,get_component_list,get_nets_list, orquery_traces.
When the reconnect succeeds, tool responses include _backend: "ipc" and
_realtime: true. If IPC is still unavailable or no board API can be opened,
the server continues to use SWIG and reports _backend: "swig" for the result.
Use check_kicad_ui, launch_kicad_ui, or get_backend_info to inspect the
current live backend status. These responses include backend,
realtime_sync, and ipc_connected.
Testing
Run the test script to verify IPC functionality:
# Make sure KiCAD is running with IPC enabled and a board open
./venv/bin/python python/test_ipc_backend.py
Architecture
+-------------------------------------------------------------+
| MCP Server (TypeScript/Node.js) |
+---------------------------+---------------------------------+
| JSON commands
+---------------------------v---------------------------------+
| Python Interface Layer |
| +--------------------------------------------------------+ |
| | kicad_interface.py | |
| | - Routes commands to IPC or SWIG handlers | |
| | - IPC_CAPABLE_COMMANDS dict defines routing | |
| +--------------------------------------------------------+ |
| +--------------------------------------------------------+ |
| | kicad_api/ipc_backend.py | |
| | - IPCBackend (connection management) | |
| | - IPCBoardAPI (board operations) | |
| +--------------------------------------------------------+ |
+---------------------------+---------------------------------+
| kicad-python (kipy) library
+---------------------------v---------------------------------+
| Protocol Buffers over UNIX Sockets |
+---------------------------+---------------------------------+
|
+---------------------------v---------------------------------+
| KiCAD 9.0+ (IPC Server) |
+-------------------------------------------------------------+
Known Limitations
- KiCAD must be running: Unlike SWIG, IPC requires KiCAD to be open
- Project creation: Not supported via IPC, uses file system
- Footprint library access: Uses hybrid approach (SWIG loads from library, IPC places)
- Delete trace: Falls back to SWIG (IPC API doesn't support direct deletion)
- Reconnect still requires IPC prerequisites: Runtime reconnect only succeeds when KiCAD is running with IPC enabled and a board is available
- Some operations may not work as expected: This is experimental code
Troubleshooting
"Connection failed"
- Ensure KiCAD is running
- Enable IPC API:
Preferences > Plugins > Enable IPC API Server - Check if a board is open
- If MCP started before KiCAD, call
check_kicad_uior retry an IPC-capable board tool after KiCAD and the board are ready
"kicad-python not found"
pip install kicad-python
"Version mismatch"
- Update kicad-python:
pip install --upgrade kicad-python - Ensure KiCAD 9.0+ is installed
"No board open"
- Open a board in KiCAD's PCB editor before connecting
File Structure
python/kicad_api/
├── __init__.py # Package exports
├── base.py # Abstract base classes
├── factory.py # Backend auto-detection
├── ipc_backend.py # IPC implementation
└── swig_backend.py # Legacy SWIG wrapper
python/
└── test_ipc_backend.py # IPC test script
Future Work
- More comprehensive testing of all IPC commands
- Footprint library integration via IPC (when kipy supports it)
- Schematic IPC support (when available in kicad-python)
- Event subscriptions to react to changes made in KiCAD UI
- Multi-board support
Related Documentation
- ROADMAP.md - Project roadmap
- IPC_API_MIGRATION_PLAN.md - Migration details
- REALTIME_WORKFLOW.md - Collaboration workflows
- kicad-python docs - Official API docs
Last Updated: 2026-03-21