KiCAD-MCP-Server

[https://github.com/mixelpixx/KiCAD-MCP-Server/discussions/73 **](https://github.com/mixelpixx/KiCAD-MCP-Server/discussions/73)[Konnect**is this project rebuilt from scratch in Rust as a native KiCAD 10 plugin: a single binary with no runtime dependencies, built on KiCAD's official IPC API instead of SWIG, with 171 tools, bundled Claude skills and agents, design-review audits, and a manufacturing pipeline. It's where new development happens — licensed AGPL-3.0 (free for individuals and open source; commercial licenses available for businesses). This Python/TypeScript server remains fully open (MIT) and maintained. A Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with KiCAD for PCB design automation. Built on the MCP 2025-06-18 specification, this server provides comprehensive tool schemas and real-time project state access for intelligent PCB design workflows. The](https://github.com/mixelpixx/Konnect)[Model Context Protocolis an open standard from Anthropic that allows AI assistants to securely connect to external tools and data sources. This implementation provides a standardized bridge between AI assistants and KiCAD, enabling natural language control of PCB design operations. - 169 tools across 15 categories with JSON Schema validation - Keyword tool discovery via`search_tools`/`get_category_tools` - 8 dynamic resources exposing project state - Complete schematic workflow with 27 tools and dynamic symbol loading (~10,000 symbols) - Freerouting autorouter integration (Java, Docker, or Podman) - Custom footprint and symbol creation tools - JLCPCB parts integration with 2.5M+ component catalog and local library search - Datasheet enrichment via LCSC - Full MCP 2025-06-18 protocol compliance - Cross-platform support (Linux, Windows, macOS) - Real-time KiCAD UI integration via IPC API (experimental) - Comprehensive error handling and logging ## Try out Arduino MCP - now you can get Claude to help in the IDE, real time!: ](https://modelcontextprotocol.io/)[https://github.com/mixelpixx/arduino-ide The Node-Python protocol had no request IDs: after one timeout, the next command was silently resolved with the*previous*command's late result, and every response after that was off by one. Tool calls now carry an ID that Python echoes back; stale responses are discarded instead of mis-delivered (#373). The MCP transport also connects before Python spawns, so clients no longer stack up against a silent server for up to two minutes during pcbnew warm-up (#377). `add_symbol_property`dropped a closing paren on every call and could splice a unit symbol into a top-level sibling (#362, @karu2003). And S-expression escaping is now symmetric: reads (#336) and writes (#324) share one escape-aware implementation, so a property value containing`\"`survives a round-trip — 419 of KiCad's own stock symbol files carry such values. - **Validation**:`validate_schematic`,`validate_symbol_library`— locate structural damage with line/column, confirmed via`kicad-cli`on a copy. - **Library tables**:`list_library_table`,`remove_library_table_entry`,`set_library_table_uri`— the missing CRUD around`register_*_library`. - **Symbol editing**:`set_symbol_pin_type`(bulk pin type fixes with dry-run),`find_duplicate_symbols`(the same part stored twice). - **Back-annotation**:`backannotate_footprints`— PCB footprint choices flow back to the schematic, the reverse of`sync_schematic_to_board`. All by @karu2003. With #359 (@AmirF194) registering 15 existing symbol tools,`search_tools`now indexes 169 tools in 15 categories. - `autoroute`stages its`.dsn`/`.ses`work files in a temp directory and cleans up on every exit — no more litter next to your board, no stale-SES imports, and a killed run says "terminated externally" instead of`exit code 4294967295`(#249, scoped by @Dewieinns' traces). - Placed symbols inherit the library's default Footprint (#300, implementation by @stefangordon). - `add_layer`actually adds inner copper layers (#222) — it previously wrote to non-copper layer IDs and renamed F.SilkS. - `sync_schematic_to_board`matches by symbol UUID, not just refdes (#250). - JLCPCB tools decode the new upstream`source-db-v2`schema (#352, @stefanobaldo) and degrade gracefully when the parts DB is unavailable (#264, @fage2022). - `setup-macos.sh --verify`now fails when Python requirements are missing instead of passing on a server that cannot start (#350, @francisrath). Deleting anything from a board — a component, a trace, a board outline — worked exactly once. The next operation, even a pure read, failed with a`SwigPyObject`error, and only`close_project`then`open_project`recovered.`BOARD.Remove()`hands C++ ownership to Python, so dropping the reference ran a destructor on an object KiCad still pointed at, corrupting SWIG state process-wide. Six call sites were affected; all now use`BOARD.Delete()`. - **Vendor PCB import**:`import_pcb`converts PADS, Altium, Eagle, CADSTAR, Fabmaster, P-CAD, SolidWorks PCB and binary Cadence Allegro`.brd`files via KiCad 10's native importer. - **Hierarchical schematics**:`remove_hierarchical_sheet`,`set_sheet_property`,`get_sheet_properties`, and`hierarchical_place`for arranging footprints by schematic hierarchy. - **Schematic lint and repair**:`lint_offgrid`finds and safely snaps off-grid geometry that silently breaks junction placement;`repair_flat_symbols`fixes SnapEDA/SamacSys symbols that crash kicad-skip;`lint_schematic_cosmetic`tidies pin names and label orientation. - **Board origins**:`set_board_origin`/`get_board_origin`. ### Your`.kicad_pro`net classes stop disappearing Board saves no longer let pcbnew serialize a stale in-memory project model over your hand-edited net classes and`netclass_patterns`. Opening a project no longer rewrites the file at all. ### Breaking: schematic tools fail loudly on an unparseable sheet Tools that used to return partial or empty results now return a structured`schematic_load_failed`error naming the offending symbols. Silently skipping a broken sheet produced an incomplete pad-to-net map reported as success, which is worse.`repair_flat_symbols`fixes the usual cause. See](https://github.com/mixelpixx/arduino-ide)[KNOWN_ISSUES.mdsection 7. ### 20 new board-lifecycle and geometry tools - **Lifecycle**:`open_board`,`reload_board`,`save_board`,`save_as`,`is_dirty`,`discard_or_reload`,`create_board_from_schematic`. - **Graphics editing**:`clear_board_outline`,`replace_board_outline`,`list_graphics`,`delete_graphic`,`update_graphic`,`move_footprint_text`. - **Geometry queries**:`batch_move_components`,`get_component_geometry`,`get_pads`,`get_net_pads`,`get_ratsnest`,`estimate_airwire_lengths`,`check_placement_clearance`. All of them respect backend session pinning, so a board saved while KiCad's GUI owns the session routes to the GUI rather than writing a stale in-memory copy — including the awkward case where`save_as`changes the board's identity mid-session. - `pre-commit run --all-files`(black, isort, prettier, flake8, mypy, eslint) is now a real CI gate, which is what CONTRIBUTING has always claimed. - `npm run lint`used to run`black`in**write**mode against whatever`black`was on`PATH`, silently reformatting your working tree with a version that disagreed with CI. It now checks only;`npm run format:py`is the write path. - The README's tool count is pinned to the registry by a test, so it self-corrects instead of drifting. ### Three tools that were registered but had no backend now work - `assign_net_to_class`,`check_clearance`and`set_layer_constraints`each had a full schema and a router entry but no dispatch handler, so every call returned`Unknown command`. Found by a documentation-coverage audit. - Per-layer constraints are written to a project-scoped`.kicad_dru`custom-rules file, which`kicad-cli pcb drc`and the GUI both pick up — there is no pcbnew API for them. - `autoroute`was abandoned by the Node bridge at 30 s while Freerouting was still running, reporting failure against a valid`.ses`that existed on disk. Its timeout now derives from the`timeout`and`attempts`you pass. - `get_board_2d_view`omitted`--layers`entirely when no layers were given, and KiCad 9+ then refuses the export — producing no file at all. - `create_zone`raised`AttributeError`on every call over the IPC backend. - `search_parts_registry`/`get_registry_part`/`download_registry_part`reuse a verified existing footprint or symbol instead of generating one. Downloads are host-allowlisted, extension-checked and size-capped. - `get_jlcpcb_part`returns live stock and tiered pricing when JLCPCB Open Platform credentials are configured, falling back to the local snapshot. - The Python job had been a no-op in four independent ways, and Actions was disabled repo-wide — 32 failed runs and 0 successes across the project's whole history. All 1551 Python and 63 TypeScript tests now gate every push. - `import_symbol`/`export_symbol`/`rename_symbol`copy a symbol between`.kicad_sym`libraries, extract one to a standalone file, and rename a symbol including its sub-symbol shards and any`(extends ...)`references from derived symbols in the same library. - `add_symbol_property`and`add_library_symbol_property`set custom BOM fields (Manufacturer, MPN, LCSC, ...) on a library symbol or on a schematic's cached definition. - `update_symbol_from_library`refreshes cached`lib_symbols`definitions across one schematic, a list, or every project under a directory — the programmatic equivalent of KiCad's Update Symbol from Library. - `replace_instance_lib_ids`swaps`lib_id`references per an explicit old-to-new mapping, for migrating a schematic between libraries. - Library directories, resolved paths, extracted symbol blocks, and parsed symbol lists are now cached process-wide instead of being rebuilt for every component add. Staleness guards revalidate paths and track source`mtime_ns`, and the mutating write paths clear the caches explicitly. - Every`.kicad_sym`and schematic write raised`TypeError`on Python 3.9, the project's declared floor —`Path.write_text`did not accept`newline`until 3.10. - JLCPCB part search could not find hyphenated MPNs. - Eagle import wrote a KiCad 9 schematic header; it now writes the KiCad 10 header, verified against real`kicad-cli`10.0. - Component placement snaps to the 1.27 mm grid,`import_ses`no longer creates phantom slashless nets, and`export_dsn`/`autoroute`keep`.kicad_pro`net classes. - `import_eagle_schematic`converts Eagle`.sch`XML designs to KiCad format with symbol mapping, net wires, multi-gate parts, dangling-wire pruning, and ground-truth ERC reporting via`kicad-cli`. - `add_component_3d_model`/`remove_component_3d_model`for attaching STEP/WRL models to footprints. - Opt-in`KICAD_INTERACTIVE_SCHEMATIC=1`auto-confirms KiCad's reload dialog on Windows after schematic writes. - New projects start blank (no`_TEMPLATE_*`symbols leaked into user files). - `.kicad_pro`files match what KiCad itself writes. - Format version`20260101`ensures all KiCad 10.0.x builds can open generated schematics. - Derived symbols in`.kicad_symdir`libraries resolve their parent from sibling shards. - Unified install discovery finds relocated Windows installs via registry. - User env-var placeholders from`kicad_common.json`are resolved in library paths. - Phantom cross-unit pin reports in`get_wire_connections`are eliminated. ### Schematic corruption on KiCad 10 — both mechanisms fixed - **Complete instance blocks**: placed components now carry the real project name, root-sheet uuid path, per-pin uuid entries (ERC can bind wires to pins), and the full KiCad 10 field set — verified byte-equivalent to what eeschema itself writes. Previously, dragging or editing a placed symbol could crash KiCad. - **Canonical multi-line writes**: schematic tools no longer minify the whole file onto one line. Tool writes now match eeschema's "Save" byte-for-byte, with a self-check on every write that can never corrupt data. Already- minified files are repairable with`scripts/kicad_sch_reformat.py`. - **Backend session pinning**: a loaded project stays on one backend (SWIG or IPC) for its whole lifecycle — saves can no longer silently route to a stale GUI board and lose your edits. - **External-edit guard**:`save_project`refuses to overwrite a board file whose contents changed on disk since load (pass`force: true`to override). - **`close_project`**(new tool): release the project so files can be edited directly, then reopen — no more restart choreography. - `kicad-cli`and 7-Zip are resolved from their install locations even when not on PATH — un-breaking exports, ERC/DRC, netlists, board views, and the JLCPCB database download, each with actionable errors when truly missing. - `suggest_placement`: connectivity-driven PCB placement optimizer (dry-run by default, deterministic). - `suggest_schematic_declutter`: re-orients overlapping net labels without touching connectivity. Plus KiCad 10 compatibility fixes (sheet renames, sharded`.kicad_symdir`libraries, IPC`Box2`board size), correct pin geometry for rotated+mirrored and multi-unit symbols, bounded IPC connects with SWIG fallback, and a real Vitest suite for the TypeScript layer. Full details in the](https://github.com/mixelpixx/KiCAD-MCP-Server/blob/HEAD/docs/KNOWN_ISSUES.md)[CHANGELOG. ### New Tools: FFC/Ribbon Cable Passthrough Workflow A complete workflow for designing passthrough adapter boards (e.g. Raspberry Pi CSI cable adapters) is now supported: - `connect_passthrough`— wires all pins of one connector to the matching pins of another in the schematic (J1 pin N → J2 pin N, auto-named nets). - `sync_schematic_to_board`— imports the net assignments into the PCB. - `route_pad_to_pad`— routes each connection with automatic via insertion when pads are on opposite copper layers. - `snapshot_project`— saves a named checkpoint into`<project>/snapshots/`. - **Via insertion for B.Cu footprints**—`route_pad_to_pad`now correctly detects when a footprint is on B.Cu and inserts the required via. (KiCAD 9 SWIG returned`F.Cu`for all SMD pads regardless of layer — fixed.) - **Board outline rounded corners**—`add_board_outline`now correctly applies`cornerRadius`when`shape="rounded_rectangle"`. - **B.Cu placement hang**— placing a footprint on B.Cu no longer causes a ~30s freeze in KiCAD 9. Set`KICAD_MCP_DEV=1`in your Claude Desktop MCP environment to automatically save the MCP session log into the project's`logs/`folder on every`export_gerber`and`snapshot_project`call. Useful for debugging and for attaching to GitHub issues. ``` `"env": { "KICAD_MCP_DEV": "1" }` ``` **Privacy warning:**The session log contains your full tool call history (including file paths and design details).**Review or delete`logs/`before sharing a project directory publicly.** See](https://github.com/mixelpixx/KiCAD-MCP-Server/blob/HEAD/CHANGELOG.md)[CHANGELOGfor the full list of changes in this release. ### Critical Schematic Workflow Fix + Complete Wiring System (Issue #26) The schematic workflow was completely broken in previous versions -**this is now fixed AND dramatically enhanced!** - `create_project`only created PCB files, no schematics - `add_schematic_component`called non-existent API methods - Schematics couldn't be created or edited at all - Only 13 component types available (severe limitation) - No working wire/connection functionality - `create_project`now creates both .kicad_pcb and .kicad_sch files - Added pre-configured template schematics with 13 common component types - Rewrote component placement to use proper`clone()`API **Phase 2: Dynamic Symbol Loading (BREAKTHROUGH!)** - **Access to ALL ~10,000 KiCad symbols**from standard libraries - Automatic detection and dynamic loading from`.kicad_sym`library files - Zero configuration required - just specify library and symbol name - Seamless integration with existing MCP tools - Full S-expression parsing and injection system **Phase 3: Intelligent Wiring System (NEW in v2.1.0)** - **Automatic pin location discovery**with rotation support (0°, 90°, 180°, 270°) - **Smart wire routing**(direct, orthogonal horizontal-first, orthogonal vertical-first) - **Power symbol support**(VCC, GND, +3V3, +5V, etc.) - **Wire graph analysis**- geometric tracing for net connectivity - **Net label management**(local, global, hierarchical labels) - **Netlist generation**with accurate component/pin connections **Technical Architecture:**The kicad-skip library cannot create symbols or wires from scratch. We implemented a comprehensive solution: - **Static Templates:**13 pre-configured symbols (R, C, L, LED, etc.) for instant use - **Dynamic Loading:**On-demand injection of ANY symbol from KiCad libraries: - Parse`.kicad_sym`library files using S-expression parser - Inject symbol definition into schematic's`lib_symbols`section - Create offscreen template instance - Reload schematic so kicad-skip sees new template - Clone template to create actual component ``` `# Load power symbols dynamically loader.load_symbol_dynamically(sch_path, "power", "VCC") # Place components with auto-rotation ComponentManager.add_component(sch, { "type": "STM32F103C8Tx", "library": "MCU_ST_STM32F1", "reference": "U1", "x": 100, "y": 100, "rotation": 0 }) # Connect with intelligent routing ConnectionManager.add_connection(sch_path, "U1", "1", "R1", "2", routing="orthogonal_h") # Connect to power nets ConnectionManager.connect_to_net(sch_path, "U1", "VDD", "VCC") # Analyze connectivity connections = ConnectionManager.get_net_connections(sch, "VCC", sch_path) # Returns: ](https://github.com/mixelpixx/KiCAD-MCP-Server/blob/HEAD/CHANGELOG.md)[{"component": "U1", "pin": "VDD"}, {"component": "R1", "pin": "1"}]` ``` - Component placement: 100% passing - Dynamic symbol loading: 10,000+ symbols accessible - Wire creation: 100% passing (8/8 connections in test circuit) - Pin discovery: Rotation-aware, sub-millimeter accuracy - Net connectivity: 100% accurate (VCC: 2 connections, GND: 4 connections) - Netlist generation: Working with accurate pin-level connections See[Schematic Tools Referencefor the complete schematic tool documentation, and the](https://github.com/mixelpixx/KiCAD-MCP-Server/blob/HEAD/docs/SCHEMATIC_TOOLS_REFERENCE.md)[Headless Authoring Guidefor field-tested practice driving these tools without the KiCad GUI. We are currently implementing and testing the KiCAD 9.0 IPC API for real-time UI synchronization: - Changes made via MCP tools appear immediately in the KiCAD UI - No manual reload required when IPC is active - Hybrid backend: uses IPC when available, falls back to SWIG API - IPC runtime reconnect: if MCP has fallen back to SWIG, IPC-capable board tools retry IPC after KiCAD launches instead of staying on SWIG for the entire session - 20+ commands now support IPC including routing, component placement, and zone operations Note: IPC features are under active development and testing. Enable IPC in KiCAD via Preferences > Plugins > Enable IPC API Server. For OpenCode on Windows, the backend can be configured as`auto`,`ipc`, or`swig`during setup. See](https://github.com/mixelpixx/KiCAD-MCP-Server/blob/HEAD/docs/HEADLESS_AUTHORING.md)[OpenCode (Windows)for the configuration command and backend options. We've implemented an intelligent tool router to keep AI context efficient while maintaining full functionality: - **22 direct tools**always visible for high-frequency operations - **113 routed tools**organized into 14 categories (board, component, export, drc, schematic, library, symbol_pins, schematic_hierarchy, schematic_layout, schematic_batch, routing, autoroute, validation, parts-registry) - **4 router tools**for discovery and execution: - `list_tool_categories`- Browse all available categories - `get_category_tools`- View tools in a specific category - `search_tools`- Find tools by keyword - `execute_tool`- Run any tool with parameters **Why this matters:**By organizing tools into discoverable categories, Claude can intelligently find and use the right tool for your task without loading all 122 tool schemas into every conversation. This reduces context consumption while maintaining full access to all functionality. **Usage is seamless:**Just ask naturally - "export gerber files" or "add mounting holes" - and Claude will discover and execute the appropriate tools automatically. Complete integration with JLCPCB's parts catalog, providing two complementary approaches for component selection: - **Local Symbol Libraries**- Search JLCPCB libraries installed via KiCAD Plugin and Content Manager (contributed by](#opencode-windows)[@l3wi) - **JLCPCB API Integration**- Access the complete 2.5M+ parts catalog with real-time pricing and stock data - Real-time pricing with quantity breaks (1+, 10+, 100+, 1000+) - Stock availability checking - Basic vs Extended library type identification (Basic = free assembly) - Intelligent cost optimization with alternative part suggestions - Package-to-footprint mapping for KiCAD compatibility - Parametric search by category, package, manufacturer - Local SQLite database for fast offline searching - No API credentials required for local library search **Why this matters:**JLCPCB offers PCB assembly services where Basic parts have no assembly fee, while Extended parts charge $3 per unique component. This integration helps you find the cheapest components with the best availability, potentially saving hundreds of dollars on assembly costs for production runs. See](https://github.com/l3wi)[JLCPCB Usage Guidefor detailed setup and usage instructions. Every tool now includes complete JSON Schema definitions with: - Detailed parameter descriptions and constraints - Input validation with type checking - Required vs. optional parameter specifications - Enumerated values for categorical inputs - Clear documentation of what each tool does Access project state without executing tools: - `kicad://project/current/info`- Project metadata - `kicad://project/current/board`- Board properties - `kicad://project/current/components`- Component list (JSON) - `kicad://project/current/nets`- Electrical nets - `kicad://project/current/layers`- Layer stack configuration - `kicad://project/current/design-rules`- Current DRC settings - `kicad://project/current/drc-report`- Design rule violations - `kicad://board/preview.png`- Board visualization (PNG)](https://github.com/mixelpixx/KiCAD-MCP-Server/blob/HEAD/docs/JLCPCB_USAGE_GUIDE.md)