kicad-mcp-server/docs/IPC_BACKEND_STATUS.md

KiCAD IPC Backend Implementation Status

Status: 🟢 FULLY INTEGRATED Date: 2025-11-30 KiCAD Version: 9.0.6 kicad-python Version: 0.5.0

---

Overview

The IPC backend is now fully integrated as the default backend for all MCP tools. When KiCAD is running with IPC enabled, all commands automatically use real-time UI synchronization. Changes made through the MCP tools appear instantly in the KiCAD UI without requiring manual reload.

SWIG backend is deprecated and will be removed in a future version when KiCAD removes it (KiCAD 10.0).

Key Benefits

Feature	SWIG (Old)	IPC (New)
UI Updates	Manual reload required	Instant
Undo/Redo	Not supported	Transaction support
API Stability	Deprecated, will break	Stable, versioned
Connection	File-based	Live socket connection
Future Support	Removed in KiCAD 10.0	Official & maintained

Implemented Features

Automatic IPC Routing

The following MCP commands automatically use IPC when available:

Command	IPC Handler	Real-time
route_trace	_ipc_route_trace	Yes
add_via	_ipc_add_via	Yes
add_net	_ipc_add_net	Yes
add_text	_ipc_add_text	Yes
add_board_text	_ipc_add_text	Yes
set_board_size	_ipc_set_board_size	Yes
get_board_info	_ipc_get_board_info	Yes
place_component	_ipc_place_component	Yes
move_component	_ipc_move_component	Yes
delete_component	_ipc_delete_component	Yes
get_component_list	_ipc_get_component_list	Yes
save_project	_ipc_save_project	Yes

Core Connection

• Connect to running KiCAD instance
• Auto-detect socket path (/tmp/kicad/api.sock)
• Version checking and validation
• Ping/health check
• Auto-fallback to SWIG when IPC unavailable
• Change notification callbacks

Board Operations

• Get board reference
• Get/Set board size (via Edge.Cuts)
• List enabled layers
• Save board
• Get board bounding box

Component Operations

• List all components
• Place component (real-time)
• Move component (real-time)
• Delete component (real-time)
• Get component properties

Routing Operations

• Add track (real-time)
• Add via (real-time)
• Get all tracks
• Get all vias
• Get all nets

UI Integration

• Add text to board (real-time)
• Get current selection
• Clear selection
• Refill zones

Transaction Support

• Begin transaction
• Commit transaction (with description)
• Rollback transaction
• Proper undo/redo in KiCAD

Usage

Prerequisites

1. KiCAD 9.0+ must be running
2. IPC API must be enabled: Preferences > Plugins > Enable IPC API Server
3. A board must be open in the PCB editor

Installation

pip install kicad-python

Basic Usage

from kicad_api import create_backend

# Auto-detect and connect
backend = create_backend()  # Will try IPC first, fall back to SWIG
backend.connect()

# Get board API
board = backend.get_board()

# Operations appear instantly in KiCAD UI!
board.add_track(
    start_x=100.0, start_y=100.0,
    end_x=120.0, end_y=100.0,
    width=0.25, layer="F.Cu"
)

# With transaction support for undo
board.begin_transaction("Add components")
board.place_component("R1", "Resistor_SMD:R_0603", 50, 50)
board.place_component("C1", "Capacitor_SMD:C_0603", 60, 50)
board.commit_transaction("Added R1 and C1")  # Single undo step

Force Backend Selection

# Force IPC backend
backend = create_backend('ipc')

# Force SWIG backend (deprecated)
backend = create_backend('swig')

# Or via environment variable
# export KICAD_BACKEND=ipc

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

The test script will:

1. Connect to KiCAD
2. List components on the board
3. Add a test track (visible instantly in UI)
4. Add a test via (visible instantly in UI)
5. Add test text (visible instantly in UI)
6. Read the current selection

Architecture

┌─────────────────────────────────────────────────────────────┐
│              MCP Server (TypeScript/Node.js)                 │
└──────────────────────┬──────────────────────────────────────┘
                       │ JSON commands
┌──────────────────────▼──────────────────────────────────────┐
│              Python Interface Layer                          │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  kicad_api/ipc_backend.py                              │ │
│  │  - IPCBackend (connection management)                  │ │
│  │  - IPCBoardAPI (board operations)                      │ │
│  └────────────────────────────────────────────────────────┘ │
└──────────────────────┬──────────────────────────────────────┘
                       │ kicad-python (kipy) library
┌──────────────────────▼──────────────────────────────────────┐
│          Protocol Buffers over UNIX Sockets                  │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────────┐
│              KiCAD 9.0+ (IPC Server)                         │
│              Changes appear instantly in UI!                 │
└─────────────────────────────────────────────────────────────┘

Known Limitations

1. KiCAD must be running: Unlike SWIG, IPC requires KiCAD to be open
2. Project creation: Must be done through KiCAD UI or file system
3. Footprint library access: Limited - best to use library management separately
4. Layer management: Layers are predefined in KiCAD

Troubleshooting

"Connection failed"

• Ensure KiCAD is running
• Enable IPC API: Preferences > Plugins > Enable IPC API Server
• Check if a board is open

"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 (NEW)
└── swig_backend.py      # Legacy SWIG wrapper

python/
└── test_ipc_backend.py  # IPC test script

Future Enhancements

1. Footprint library integration via IPC - Load footprints directly
2. Schematic IPC support - When available in kicad-python
3. Event subscriptions - React to changes made in KiCAD UI
4. Multi-board support - Handle multiple open boards

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: 2025-11-30 Maintained by: KiCAD MCP Team