kicad-mcp-server/docs/VISUAL_FEEDBACK.md

Visual Feedback: Seeing MCP Changes in KiCAD UI

This document explains how to see changes made by the MCP server in the KiCAD UI in real-time or near-real-time.

Current Status

Active Backend: Hybrid SWIG/IPC

Real-time Updates: Available for IPC-backed commands when KiCAD IPC is connected

SWIG Fallback: File-based commands still require KiCAD to reload from disk

IPC Re-detect: IPC-enabled tools detect at runtime if IPC is available again and switch from SWIG to IPC.

---

🎯 Best Current Workflow (Hybrid IPC + SWIG)

Setup

1. Open your project in KiCAD PCB Editor

   pcbnew /tmp/kicad_test_project/New_Project.kicad_pcb
   

2. Make changes via MCP (Claude Code, Claude Desktop, etc.)

   • Example: Add board outline, mounting holes, etc.
   • Each operation saves the file automatically

3. Check whether reload is needed

   • If the MCP response reports _backend: "ipc" and _realtime: true, the change should appear in KiCAD immediately.
   • If the MCP response reports _backend: "swig" or _realtime: false, reload the board from disk.
   • Option A (Automatic): KiCAD 8.0+ detects file changes and shows a reload prompt.
   • Option B (Manual): File → Revert to reload from disk.

Workflow Example

┌─────────────────────────────────────────────────────────┐
│ Terminal: Claude Code                                   │
├─────────────────────────────────────────────────────────┤
│ You: "Create a 100x80mm board with 4 mounting holes"   │
│                                                          │
│ Claude: ✓ Added board outline (100x80mm)               │
│         ✓ Added mounting hole at (5,5)                  │
│         ✓ Added mounting hole at (95,5)                 │
│         ✓ Added mounting hole at (95,75)                │
│         ✓ Added mounting hole at (5,75)                 │
│         ✓ Saved project                                 │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│ KiCAD PCB Editor                                        │
├─────────────────────────────────────────────────────────┤
│ [Reload prompt appears]                                 │
│ "File has been modified. Reload?"                       │
│                                                          │
│ Click "Yes" → Changes appear instantly! 🎉              │
└─────────────────────────────────────────────────────────┘

---

IPC Backend: Real-Time Updates (Experimental)

When KiCAD is running with the IPC API enabled, supported MCP board tools can use the IPC backend for true real-time UI updates instead of relying on file save/reload.

How It Works

Agent → MCP → IPC connection → Running KiCAD → Instant UI Update

No file reloading is required for commands that successfully use IPC. Tool responses include _backend: "ipc" and _realtime: true when the IPC path was used. If IPC is unavailable, the server falls back to SWIG and the manual reload workflow still applies. If IPC becomes available during the session, IPC-capable tools can reconnect and use IPC without restarting the MCP server.

IPC Setup

1. Enable IPC in KiCAD:

   • Preferences → Plugins → Enable IPC API Server
   • Restart KiCAD if required

2. Install kicad-python:

   pip install kicad-python
   

3. Configure MCP Server

   The default auto backend mode is recommended when you want SWIG fallback plus runtime reconnect. To make the setting explicit, add:

   {
     "env": {
       "KICAD_BACKEND": "auto"
     }
   }
   

   Use strict ipc mode only when you want startup to fail if IPC is not available:

   {
     "env": {
       "KICAD_BACKEND": "ipc"
     }
   }
   

4. Start KiCAD and open a board, or use launch_kicad_ui.

The MCP server can start before KiCAD. In auto backend mode, IPC-capable board tools retry IPC at runtime after KiCAD is available, so agents can keep using standard tools such as get_board_info, get_layer_list, get_component_list, get_nets_list, and query_traces.

Current IPC Status

Feature	Status
Connection to KiCAD	Working when KiCAD IPC is enabled
Board operations	Partially implemented via IPC
Component operations	Partially implemented / hybrid
Routing operations	Partially implemented via IPC
SWIG fallback	Used automatically in auto mode when IPC is unavailable
Runtime reconnect to IPC	Used automatically in auto mode for IPC-capable board tools

---

🛠️ Monitoring Helper (Optional)

A helper script is available to monitor file changes:

# Watch for changes and notify
./scripts/auto_refresh_kicad.sh /tmp/kicad_test_project/New_Project.kicad_pcb

This will print a message each time the MCP server saves changes.

---

💡 Tips for Best Experience

1. Side-by-Side Windows

┌──────────────────┬──────────────────┐
│  Claude Code     │   KiCAD PCB      │
│  (Terminal)      │   Editor         │
│                  │                  │
│  Making changes  │  Viewing results │
└──────────────────┴──────────────────┘

2. Quick Reload Workflow

• Keep KiCAD focused in one window
• Make changes via Claude in another
• Press Alt+Tab → Click "Reload" → See changes
• Repeat

3. Save Frequently

The MCP server auto-saves after each operation, so changes are immediately available for reload.

4. Verify Before Complex Operations

For complex changes (multiple components, routing, etc.):

1. Make the change
2. Confirm the change in KiCAD; reload only if the response used SWIG
3. Verify it looks correct
4. Proceed with next change

---

🔍 Troubleshooting

KiCAD Doesn't Detect File Changes

Cause: Some KiCAD versions or configurations don't auto-detect Solution: Use File → Revert manually

Changes Don't Appear After Reload

Cause: MCP operation may have failed Solution: Check the MCP response for success: true

Changes Still Require Reload

Cause: The tool response reported _backend: "swig" or _realtime: false. SWIG-backed commands write files directly and still require KiCAD to reload the board from disk.

Solution: Ensure KiCAD is running with IPC enabled and a board is open, then retry the IPC-capable board tool. If IPC reconnect succeeds, the response will report _backend: "ipc" and _realtime: true.

File is Locked

Cause: KiCAD has the file open exclusively Solution:

• KiCAD should allow external modifications
• If not, close the file in KiCAD, let MCP make changes, then reopen

---

Last Updated: 2025-10-26 Version: 2.0.0-alpha.1