MCPkicad: Instructions file for Claude Code

KiCAD MCP Server

What This Project Is

An MCP (Model Context Protocol) server that enables AI assistants to design PCBs and schematics in KiCAD. It has a TypeScript frontend (MCP server, tool registration, STDIO transport) and a Python backend (KiCAD interaction via pcbnew SWIG API and kicad-skip for schematics).

Architecture

AI Client (Claude, etc.)
  ↕ STDIO (MCP protocol)
TypeScript Server (src/)
  ↕ JSON over stdin/stdout (child process)
Python Backend (python/)
  ↕ pcbnew SWIG API / kicad-skip / S-expression manipulation
KiCAD files (.kicad_pcb, .kicad_sch, .kicad_pro)

TypeScript Layer (src/)

• index.ts — Entry point, starts MCP server
• server.ts — KiCADMcpServer class, spawns Python child process (with auto-restart on crash), registers all tools/resources/prompts
• config.ts — Zod-validated config loading from config/
• logger.ts — Logger (stderr only; stdout reserved for MCP protocol)
• tools/*.ts — Tool registration using @modelcontextprotocol/sdk. Each tool calls callKicadScript(command, args) which sends JSON to the Python process
• resources/*.ts — MCP resource handlers
• prompts/*.ts — MCP prompt templates

Python Layer (python/)

• kicad_interface.py — Main entry point. Reads JSON commands from stdin, dispatches to command handlers, returns JSON on stdout. Supports IPC and SWIG backends. WARNING: This is a 7000+ line god file with duplicated pin math in 7 handlers. When fixing pin calculations, check ALL inline pin calc sites, not just pin_locator.py. Contains shared geometry parser _parse_schematic_geometry(), content-based static helpers _delete_component_from_content(), _edit_component_in_content(), T-junction helpers _point_on_wire_segment() and _find_connected_wires(), and a shared PinLocator instance (self.pin_locator).
• commands/ — Command handlers organized by domain:
  • schematic.py — SchematicManager (create schematic, template-based)
  • component_schematic.py — ComponentManager (add/edit/delete/move components using kicad-skip + dynamic symbol loading). add_component snaps to 1.27mm grid. remove_component uses text-based balanced-paren deletion (not kicad-skip _elements).
  • connection_schematic.py — ConnectionManager (wires, net labels, connections)
  • wire_manager.py — WireManager (thin delegation layer to sexp_writer.py)
  • pin_locator.py — PinLocator (pin position discovery via S-expr parsing, handles rotation + mirror)
  • sexp_writer.py — Text-based insertion/deletion for .kicad_sch files (wires, labels, junctions, no-connects, wire splitting). All writes use f.flush() + os.fsync(). Has _to_content/_from_content variants for all operations including add_label_to_content, add_polyline_wire_to_content, split_wire_at_point_in_content, delete_no_connect_from_content. Wire placement (add_wire, add_polyline_wire) now auto-detects T-junctions and adds junction dots via auto_add_t_junctions(). Also has _parse_wire_segments(), _parse_existing_junctions(), and _point_on_wire_mid() helpers for T-junction spatial analysis.
  • net_analysis.py — Net-level analysis using union-find graph. build_net_graph() builds complete pin→net mapping in O(W+L+P) via union-find with spatial-indexed T-junction detection. Query functions: get_component_nets, get_net_components, get_pin_net_name, export_netlist_summary, validate_component_connections, find_shorted_nets, find_single_pin_nets.
  • component.py — Board-level component operations (via pcbnew)
  • routing.py — Trace routing (via pcbnew)
  • board.py, board/*.py — Board operations (layers, outline, size, 2D view)
  • project.py — Project creation/management
  • library.py, library_schematic.py, library_symbol.py — Library operations
  • dynamic_symbol_loader.py — Loads symbols from KiCAD libraries at runtime. _extract_symbol_block handles both multi-line and single-line .kicad_sym files via balanced-paren traversal.
  • footprint.py — Footprint operations
  • export.py — Export (Gerber, PDF, SVG, BOM, 3D, etc.)
  • design_rules.py — DRC rules
  • jlcpcb.py, jlcpcb_parts.py, jlcsearch.py — JLCPCB integration
  • datasheet_manager.py — Datasheet URL extraction
  • symbol_creator.py — Custom symbol creation
  • svg_import.py — SVG logo import
• kicad_api/ — Backend abstraction (SWIG vs IPC)
  • base.py — Abstract base class
  • swig_backend.py — pcbnew SWIG backend
  • ipc_backend.py — KiCAD IPC API backend (experimental)
  • factory.py — Backend factory
• schemas/tool_schemas.py — Python-side tool schema definitions
• resources/ — Resource definitions
• utils/ — Platform detection, KiCAD process management
• templates/ — Schematic templates (used by create_schematic)