KiCAD-MCP-Server

# 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 (Week 1 - SWIG Backend) **Active Backend:** SWIG (legacy pcbnew Python API) **Real-time Updates:** Not available yet **IPC Backend:** Skeleton implemented, operations coming in Weeks 2-3 --- ## 🎯 Best Current Workflow (SWIG + Manual Reload) ### Setup 1. **Open your project in KiCAD PCB Editor** ```bash 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. **Reload in KiCAD UI** - **Option A (Automatic):** KiCAD 8.0+ detects file changes and shows a reload prompt - **Option B (Manual):** File → Revert to reload from disk - **Keyboard shortcut:** None by default (but you can assign one) ### 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! 🎉 │ └─────────────────────────────────────────────────────────┘ ``` --- ## 🔮 Future: IPC Backend (Weeks 2-3) When fully implemented, the IPC backend will provide **true real-time updates**: ### How It Will Work ``` Claude MCP → IPC Socket → Running KiCAD → Instant UI Update ``` **No file reloading required** - changes appear as you make them! ### IPC Setup (When Available) 1. **Enable IPC in KiCAD** - Preferences → Advanced Preferences - Search for "IPC" - Enable: "Enable IPC API Server" - Restart KiCAD 2. **Install kicad-python** (Already installed ✓) ```bash pip install kicad-python ``` 3. **Configure MCP Server** Add to your MCP config: ```json { "env": { "KICAD_BACKEND": "ipc" } } ``` 4. **Start KiCAD first, then use MCP** - Changes will appear in real-time - No manual reloading needed ### Current IPC Status | Feature | Status | |---------|--------| | Connection to KiCAD | ✅ Working | | Version checking | ✅ Working | | Project operations | ⏳ Week 2-3 | | Board operations | ⏳ Week 2-3 | | Component operations | ⏳ Week 2-3 | | Routing operations | ⏳ Week 2-3 | --- ## 🛠️ Monitoring Helper (Optional) A helper script is available to monitor file changes: ```bash # 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. Reload in KiCAD 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 ### 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 --- ## 📅 Roadmap **Current (Week 1):** SWIG backend with manual reload **Week 2-3:** IPC backend implementation **Week 4+:** Real-time collaboration features --- **Last Updated:** 2025-10-26 **Version:** 2.0.0-alpha.1