Discussions. Get in here.
https://github.com/mixelpixx/KiCAD-MCP-Server/discussions/73
🚀 Meet Konnect — the next generation
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.
KiCAD MCP Server
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.
Overview
The Model Context Protocol is 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.
Key Capabilities:
- 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://github.com/mixelpixx/arduino-ide
What's New in v2.7.0
The bridge no longer crosses its wires
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).
Two file-corruption classes fixed
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.
8 new tools
- 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.
Quality of life
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).
Full details in the CHANGELOG.
What's New in v2.6.0
A session-killing bug is fixed
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().
10 new tools
- 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
KNOWN_ISSUES.md section 7.
Full details in the CHANGELOG.
What's New in v2.5.0
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.
Formatting is normalized and enforced
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.
Full details in the CHANGELOG.
What's New in v2.4.1
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.
Silent failures removed
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.
New part-sourcing tools
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.
CI now actually runs the test suite
- 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.
Full details in the CHANGELOG.
What's New in v2.4.0
Symbol library management
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.
Faster symbol discovery
- 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.
Fixes that restore basic operation
- 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.
Full details in the CHANGELOG.
What's New in v2.3.1
Eagle schematic import
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.
3D model tools and interactive reload
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.
Scaffolding cluster complete
- 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.
KiCad 10 compatibility
- 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.
Full details in the CHANGELOG.
What's New in v2.3.0
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.
Your edits are protected
- 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.
Works on a stock Windows install
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.
New layout tools
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
CHANGELOG.
What's New in v2.2.3
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/.
Bug Fixes (KiCAD 9 / Windows)
- 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.
Developer Mode
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 CHANGELOG for the full list of changes in this release.
What's New in v2.1.0
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!
What was broken:
create_project only created PCB files, no schematicsadd_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
Complete Implementation (3 Phases):
Phase 1: Component Placement Foundation
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
- Wire Creation: S-expression-based wire injection (bypasses kicad-skip API limitations)
- Pin Discovery: Parse symbol definitions, apply rotation transformations, calculate absolute positions
- Connectivity Analysis: Geometric wire tracing to build net connection graphs
Example - Complete Circuit Creation:
# 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: [{"component": "U1", "pin": "VDD"}, {"component": "R1", "pin": "1"}]
Test Results:
- 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 Reference for the complete schematic tool documentation, and the Headless Authoring Guide for field-tested practice driving these tools without the KiCad GUI.
IPC Backend (Experimental)
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 OpenCode (Windows) for the
configuration command and backend options.
Tool Discovery & Router Pattern
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 categoriesget_category_tools - View tools in a specific categorysearch_tools - Find tools by keywordexecute_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.
NEEDS TESTING - REPORT ISSUES
JLCPCB Parts Integration (New!)
Complete integration with JLCPCB's parts catalog, providing two complementary approaches for component selection:
Dual-Mode Architecture:
- Local Symbol Libraries - Search JLCPCB libraries installed via KiCAD Plugin and Content Manager (contributed by @l3wi)
- JLCPCB API Integration - Access the complete 2.5M+ parts catalog with real-time pricing and stock data
Key Features:
- 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 JLCPCB Usage Guide for detailed setup and usage instructions.
Comprehensive Tool Schemas
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
Resources Capability
Access project state without executing tools:
kicad://project/current/info - Project metadatakicad://project/current/board - Board propertieskicad://project/current/components - Component list (JSON)kicad://project/current/nets - Electrical netskicad://project/current/layers - Layer stack configurationkicad://project/current/design-rules - Current DRC settingskicad://project/current/drc-report - Design rule violationskicad://board/preview.png - Board visualization (PNG)
Protocol Compliance
- Updated to MCP SDK 1.21.0 (latest)
- Full JSON-RPC 2.0 support
- Proper capability negotiation
- Standards-compliant error codes
Available Tools
The server exposes every tool directly, so your assistant can call any of them without a discovery step -- just ask for what you want to accomplish. 169 tools are additionally indexed into 15 functional categories, so search_tools and get_category_tools can find one by keyword.
For the complete tool reference with access types (direct/routed/additional), see Tool Inventory.
Project Management (5 tools)
create_project - Initialize new KiCAD projectsopen_project - Load existing project filessave_project - Save current project stateget_project_info - Retrieve project metadatasnapshot_project - Save named checkpoint snapshot
Board Operations (12 tools)
set_board_size - Configure PCB dimensionsadd_board_outline - Create board edge (rectangle, circle, polygon, rounded rectangle)add_layer - Add custom layers to stackset_active_layer - Switch working layerget_layer_list - List all board layersget_board_info - Retrieve board propertiesget_board_2d_view - Generate board preview imageget_board_extents - Get board bounding boxadd_mounting_hole - Place mounting holesadd_board_text - Add text annotationsadd_zone - Add copper zone/pour with clearance settingsimport_svg_logo - Import SVG file as PCB silkscreen polygons
Component Management (16 tools)
place_component - Place single component with footprintmove_component - Reposition existing componentrotate_component - Rotate component by angledelete_component - Remove component from boardedit_component - Modify component propertiesfind_component - Search by reference or valueget_component_properties - Query component detailsadd_component_annotation - Add annotation/commentgroup_components - Group multiple componentsreplace_component - Replace with different footprintget_component_pads - Get all pad informationget_component_list - List all placed componentsget_pad_position - Get precise pad positionplace_component_array - Create component grids/patternsalign_components - Align multiple componentsduplicate_component - Copy existing component
Routing (13 tools)
add_net - Create electrical netroute_trace - Route copper traces between XY pointsroute_pad_to_pad - Route between pads with auto-via insertionadd_via - Place vias for layer transitionsdelete_trace - Remove traces (by UUID, position, or net)query_traces - Query/filter tracesget_nets_list - List all nets with statisticsmodify_trace - Change trace width, layer, or netcreate_netclass - Define net class with rulesadd_copper_pour - Create copper zones/poursroute_differential_pair - Route differential signalsrefill_zones - Refill all copper zonescopy_routing_pattern - Replicate routing between component groups
Schematic (27 tools)
Complete schematic workflow with dynamic symbol loading (~10,000 symbols) and intelligent wiring.
Component Operations:
add_schematic_component - Place symbols from any KiCad librarydelete_schematic_component - Remove componentedit_schematic_component - Edit footprint, value, reference, label positions, and arbitrary custom properties (MPN, Manufacturer, DigiKey_PN, LCSC, Voltage, Tolerance, Dielectric, …) in one batched callset_schematic_component_property - Add or update a single custom property (BOM/sourcing field) on a componentremove_schematic_component_property - Delete a single custom property from a componentget_schematic_component - Inspect every field on a component (built-in + custom) including label positionslist_schematic_components - List all componentsmove_schematic_component - Reposition componentrotate_schematic_component - Rotate componentannotate_schematic - Auto-assign reference designators
Wiring and Connections:
add_wire - Create wire between pointsdelete_schematic_wire - Remove wire segmentadd_schematic_connection - Auto-connect pins with routingadd_schematic_net_label - Add net labels (VCC, GND, signals)delete_schematic_net_label - Remove net labelconnect_to_net - Connect pin to named netconnect_passthrough - Wire all matching pins between connectors (FFC/ribbon)get_schematic_pin_locations - Get pin locations for component
Analysis and Export:
get_net_connections - Trace net connectivitylist_schematic_nets / list_schematic_wires / list_schematic_labelscreate_schematic - Create new schematic fileget_schematic_view - Rasterized schematic previewexport_schematic_svg / export_schematic_pdfrun_erc - Electrical rule checkgenerate_netlist - Generate netlist from schematicsync_schematic_to_board - Import nets/pads to PCB (F8 equivalent)
See Schematic Tools Reference for details and examples.
Design Rules / DRC (8 tools)
set_design_rules / get_design_rules - Configure and inspect rulesrun_drc - Execute design rule checkget_drc_violations - Get violation list by severitycreate_netclass / assign_net_to_class - Net class managementset_layer_constraints / check_clearance - Layer and clearance rules
Export (8 tools)
export_gerber - Gerber fabrication filesexport_pdf / export_svg - Documentation and vector graphicsexport_3d - 3D models (STEP, STL, VRML, OBJ)export_bom - Bill of materials (CSV, XML, HTML, JSON)export_netlist - Netlist (KiCad, Spice, Cadstar, OrcadPCB2)export_position_file - Component positions for pick and placeexport_vrml - VRML 3D model
Footprint Libraries (4 tools) and Symbol Libraries (4 tools)
list_libraries / list_symbol_libraries - Browse available librariessearch_footprints / search_symbols - Search across all librarieslist_library_footprints / list_library_symbols - Browse specific libraryget_footprint_info / get_symbol_info - Detailed information
Footprint Creator (4 tools) and Symbol Creator (4 tools)
Create custom components when existing libraries do not have what you need.
create_footprint / create_symbol - Build from scratch with pads/pinsedit_footprint_pad - Modify pad propertiesregister_footprint_library / register_symbol_library - Register in lib-tablelist_footprint_libraries / list_symbols_in_library - Browse custom librariesdelete_symbol - Remove symbol from library
See Footprint and Symbol Creator Guide for details.
Datasheet Tools (2 tools)
enrich_datasheets - Auto-populate datasheet URLs using LCSC part numbersget_datasheet_url - Get LCSC datasheet URL for a component
JLCPCB Integration (5 tools)
download_jlcpcb_database - Download 2.5M+ parts catalog (one-time setup)search_jlcpcb_parts - Search with parametric filtersget_jlcpcb_part - Detailed part info with pricingget_jlcpcb_database_stats - Database statisticssuggest_jlcpcb_alternatives - Find cheaper or in-stock alternatives
Freerouting Autorouter (4 tools)
autoroute - Run Freerouting autorouter (DSN export, route, SES import)export_dsn / import_ses - Manual Specctra DSN/SES workflowcheck_freerouting - Verify Java and Freerouting availability
See Freerouting Guide for setup and usage.
UI Management (2 tools)
check_kicad_ui - Check if KiCAD is runninglaunch_kicad_ui - Launch KiCAD application
Prerequisites
Required Software
KiCAD 9.0 or higher
Node.js 18 or Higher
- Download from nodejs.org
- Verify:
node --version and npm --version
Python 3.9 or Higher
- Comes bundled with KiCAD (macOS builds ship Python 3.9; Linux/Windows builds ship Python 3.11)
- Required packages (auto-installed):
- kicad-python (kipy) >= 0.5.0 (IPC API support, optional but recommended)
- kicad-skip >= 0.1.0 (schematic support)
- Pillow >= 9.0.0 (image processing)
- cairosvg >= 2.7.0 (SVG rendering)
- colorlog >= 6.7.0 (logging)
- pydantic >= 2.5.0 (validation)
- requests >= 2.32.5 (HTTP client)
- python-dotenv >= 1.0.0 (environment)
MCP Client
Choose one:
Supported Platforms
- Linux (Ubuntu 22.04+, Fedora, Arch) - Primary platform, fully tested
- Windows 10/11 - Fully supported with automated setup
- macOS - Experimental support
Apply project-local configuration
Use this when you only want KiCAD MCP enabled for one project. The script writes
opencode.json in the target project root and backs up an existing file before
changing it.
.\setup-windows-opencode.ps1 -Apply -Scope project
By default, ProjectPath is the current working directory.
To configure another project, pass -ProjectPath:
.\setup-windows-opencode.ps1 -Apply -Scope project -ProjectPath "C:\path\to\your-project"
If the setup script is not located in the KiCAD MCP Server repository, pass
-McpServerPath so the generated config points to the correct dist/index.js:
.\setup-windows-opencode.ps1 `
-Apply `
-Scope project `
-ProjectPath "C:\path\to\your-project" `
-McpServerPath "C:\path\to\KiCAD-MCP-Server"
Use a custom MCP server name
Use this when testing multiple forks or keeping separate development and stable
KiCAD MCP entries.
.\setup-windows-opencode.ps1 -Apply -Scope project -Name kicad-dev
Use a custom KiCAD installation path
Use this when KiCAD is installed outside the standard Windows locations.
.\setup-windows-opencode.ps1 -Apply -Scope project -KiCadRoot "D:\Apps\KiCad\10.0"
Skip install or build steps
Use these flags when dependencies are already installed or the project is
already built.
.\setup-windows-opencode.ps1 -Apply -Scope project -SkipInstall -SkipBuild
After applying configuration
- Fully quit OpenCode.
- Start OpenCode again so it reloads
opencode.json.
- Ask OpenCode to use the
kicad MCP server and run check_kicad_ui.
Disable the OpenCode MCP server
To disable the server without removing the full configuration, set the entry to
enabled: false and restart OpenCode.
{
"mcp": {
"kicad": {
"enabled": false
}
}
}
If OpenCode is running, the MCP server process is managed by OpenCode and
normally stops when OpenCode exits.
JLCPCB Integration Setup (Optional)
The JLCPCB integration provides two modes that can be used independently or together:
Mode 1: JLCSearch Public API (Recommended - No Setup Required)
The easiest way to access JLCPCB's parts catalog:
- No API credentials needed
- No JLCPCB account required
- Access to 2.5M+ parts with pricing and stock data
- Download time: 40-60 minutes for full catalog (100-part batches due to API limit)
To download the database:
Ask Claude: "Download the JLCPCB parts database"
This creates a local SQLite database at data/jlcpcb_parts.db (3-5 GB for full 2.5M+ part catalog).
Mode 2: Local Symbol Libraries (No Setup Required)
Install JLCPCB libraries via KiCAD's Plugin and Content Manager:
- Open KiCAD
- Go to Tools > Plugin and Content Manager
- Search for "JLCPCB" or "JLC"
- Install libraries like
JLCPCB-KiCAD-Library or EDA_MCP
- Use
search_symbols to find components with pre-configured footprints and LCSC IDs
Mode 3: Official JLCPCB API (Advanced - Requires Enterprise Account)
For users with JLCPCB enterprise accounts and order history:
-
Get API Credentials
- Log in to JLCPCB
- Navigate to Account > API Management (requires enterprise approval)
- Create API Key and save your
appKey and appSecret
- Note: This requires prior order history and enterprise account approval
-
Configure Environment Variables
Add to your shell profile (~/.bashrc, ~/.zshrc, or ~/.profile):
export JLCPCB_API_KEY="your_app_key_here"
export JLCPCB_API_SECRET="your_app_secret_here"
Or create a .env file in the project root:
JLCPCB_API_KEY=your_app_key_here
JLCPCB_API_SECRET=your_app_secret_here
See JLCPCB Usage Guide for detailed documentation.
Usage Examples
Basic PCB Design Workflow
Create a new KiCAD project named 'LEDBoard' in my Documents folder.
Set the board size to 50mm x 50mm and add a rectangular outline.
Place a mounting hole at each corner, 3mm from the edges, with 3mm diameter.
Add text 'LED Controller v1.0' on the front silkscreen at position x=25mm, y=45mm.
Component Placement
Place an LED at x=10mm, y=10mm using footprint LED_SMD:LED_0805_2012Metric.
Create a grid of 4 resistors (R1-R4) starting at x=20mm, y=20mm with 5mm spacing.
Align all resistors horizontally and distribute them evenly.
Routing
Create a net named 'LED1' and route a 0.3mm trace from R1 pad 2 to LED1 anode.
Add a copper pour for GND on the bottom layer covering the entire board.
Create a differential pair for USB_P and USB_N with 0.2mm width and 0.15mm gap.
Autoroute with Freerouting
Automatically route all unconnected nets using the Freerouting autorouter.
Setup (one-time):
# 1. Download the Freerouting JAR
mkdir -p ~/.kicad-mcp
curl -L -o ~/.kicad-mcp/freerouting.jar \
https://github.com/freerouting/freerouting/releases/download/v2.0.1/freerouting-2.0.1-executable.jar
# 2. Runtime — pick ONE:
# Option A: Docker (recommended, no Java install needed)
docker pull eclipse-temurin:21-jre
# Option B: Install Java 21+ locally
# (Ubuntu/Debian) sudo apt install openjdk-21-jre
The autorouter auto-detects which runtime is available (Java 21+ direct, or Docker/Podman fallback).
Check if Freerouting is ready on my system.
Autoroute the current board using Freerouting with a 5-minute timeout.
Step-by-step workflow:
1. Open the project at ~/Projects/LEDBoard/LEDBoard.kicad_pcb
2. Check Freerouting dependencies are installed
3. Run autoroute with max 10 passes
4. Run DRC to verify the autorouted result
5. Export Gerbers to the fabrication folder
Manual DSN/SES workflow (for advanced users or external autorouters):
Export the board to Specctra DSN format.
# ... run Freerouting GUI or another autorouter externally ...
Import the routed SES file from ~/Projects/LEDBoard/LEDBoard.ses
Design Verification
Set design rules with 0.15mm clearance and 0.2mm minimum track width.
Run a design rule check and show me any violations.
Export Gerber files to the 'fabrication' folder.
Using Resources
Resources provide read-only access to project state:
Show me the current component list.
What are the current design rules?
Display the board preview.
List all electrical nets.
JLCPCB Component Selection
Finding Components with Local Libraries:
Search for ESP32 modules in JLCPCB libraries.
Find a 10k resistor in 0603 package from installed libraries.
Show me details for LCSC part C2934196.
Optimizing Costs with JLCPCB API:
Search for 10k ohm resistors in 0603 package, only Basic parts.
Find the cheapest capacitor 10uF 25V in 0805 package with good stock.
Show me pricing and stock for JLCPCB part C25804.
Suggest cheaper alternatives to C25804.
Complete Design Workflow:
I'm designing a board with an ESP32 and need to select components for JLCPCB assembly.
Search JLCPCB for ESP32-C3 modules.
Find Basic parts for: 10k resistor 0603, 100nF capacitor 0603, LED 0805.
For each component, show me the cheapest option with good stock availability.
Place these components on my board using the suggested footprints.
Database Management:
Download the JLCPCB parts database (first time setup).
Show me JLCPCB database statistics.
How many Basic parts are available?
Architecture
MCP Protocol Layer
- JSON-RPC 2.0 Transport: Bi-directional communication via STDIO
- Protocol Version: MCP 2025-06-18
- Capabilities: Tools (122), Resources (8)
- Tool Router: Intelligent discovery system with 14 categories
- Error Handling: Standard JSON-RPC error codes
TypeScript Server (src/)
- Implements MCP protocol specification
- Manages Python subprocess lifecycle
- Handles message routing and validation
- Provides logging and error recovery
- Discovery catalogue:
src/tools/registry.ts - Tool categorization and lookupsrc/tools/router.ts - list_tool_categories, get_category_tools, search_tools- Search and browse only. It does not gate which tools reach the client, so
it saves no context; indirect execution was removed in 963a39c because it
caused schema hallucination. See
ROUTER_ARCHITECTURE.md.
Python Interface (python/)
- kicad_interface.py: Main entry point, MCP message handler, command routing
- kicad_api/: Backend implementations
base.py - Abstract base classes for backendsipc_backend.py - KiCAD 9.0 IPC API backend (real-time UI sync)swig_backend.py - pcbnew SWIG API backend (file-based operations)factory.py - Backend auto-detection and instantiation
- schemas/tool_schemas.py: JSON Schema definitions for all tools
- resources/resource_definitions.py: Resource handlers and URIs
- commands/: Modular command implementations
project.py - Project operationsboard.py - Board manipulationcomponent.py - Component placementrouting.py - Trace routing and netsdesign_rules.py - DRC operationsexport.py - File generationschematic.py - Schematic designlibrary.py - Footprint librarieslibrary_symbol.py - Symbol library search (local JLCPCB libraries)jlcpcb.py - JLCPCB API clientjlcpcb_parts.py - JLCPCB parts database manager
KiCAD Integration
- pcbnew API (SWIG): Direct Python bindings to KiCAD for file operations
- IPC API (kipy): Real-time communication with running KiCAD instance (experimental)
- Hybrid Backend: Automatically uses IPC when available, falls back to SWIG
- kicad-skip: Schematic file manipulation
- Platform Detection: Cross-platform path handling
- UI Management: Automatic KiCAD UI launch/detection
Development
Building from Source
# Install dependencies
npm install
pip3 install -r requirements.txt
# Build TypeScript
npm run build
# Watch mode for development
npm run dev
Running Tests
# TypeScript tests
npm run test:ts
# Python tests
npm run test:py
# All tests with coverage
npm run test:coverage
Linting and Formatting
# Lint TypeScript and Python
npm run lint
# Format code
npm run format
Troubleshooting
Server Not Appearing in Client
Symptoms: MCP server doesn't show up in Claude Desktop or Cline
Solutions:
- Verify build completed:
ls dist/index.js
- Check configuration paths are absolute
- Restart MCP client completely
- Check client logs for error messages
Python Module Import Errors
Symptoms: ModuleNotFoundError: No module named 'pcbnew'
Solutions:
- Verify KiCAD installation:
python3 -c "import pcbnew"
- Check PYTHONPATH in configuration matches your KiCAD installation
- Ensure KiCAD was installed with Python support
Tool Execution Failures
Symptoms: Tools fail with unclear errors
Solutions:
- Check server logs:
~/.kicad-mcp/logs/kicad_interface.log
- Verify a project is loaded before running board operations
- Ensure file paths are absolute, not relative
- Check tool parameter types match schema requirements
Windows-Specific Issues
Symptoms: Server fails to start on Windows
Solutions:
- Run automated diagnostics:
.\setup-windows.ps1
- Verify Python path uses double backslashes:
C:\\Program Files\\KiCad\\10.0
- Check Windows Event Viewer for Node.js errors
- See Windows Troubleshooting Guide
Getting Help
- Check the GitHub Issues
- Review server logs:
~/.kicad-mcp/logs/kicad_interface.log
- Open a new issue with:
- Operating system and version
- KiCAD version (
python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())")
- Node.js version (
node --version)
- Full error message and stack trace
- Relevant log excerpts
Project Status
Current Version: 2.5.0
See STATUS_SUMMARY.md for the complete status matrix and CHANGELOG.md for detailed release notes.
Working Features (148 tools):
- Project management with snapshot checkpointing
- Complete board design (outline, layers, zones, mounting holes, text, SVG logos)
- Component placement with arrays, alignment, and duplication
- Advanced routing (pad-to-pad with auto-via, differential pairs, pattern copying)
- Complete schematic workflow with dynamic symbol loading (~10,000 symbols)
- Intelligent wiring system with pin discovery and smart routing
- FFC/ribbon cable passthrough workflow
- Schematic-to-board synchronization, plus footprint back-annotation from the board
- Design rule checking (DRC and ERC)
- Structural validation of schematics and symbol libraries
- Export to Gerber, PDF, SVG, 3D, BOM, netlist, position file
- Custom footprint and symbol creation
- Library table maintenance (list, remove and repoint symbol/footprint entries)
- JLCPCB parts integration (2.5M+ parts catalog)
- Datasheet enrichment via LCSC
- Freerouting autorouter integration (Java, Docker, Podman)
- UI auto-launch and management
- Full MCP 2025-06-18 protocol compliance
IPC Backend (Experimental):
- Real-time UI synchronization via the KiCAD IPC API
- 21 IPC-enabled commands with automatic SWIG fallback
- Hybrid footprint loading (SWIG for library access, IPC for placement)
Developer Mode:
Set KICAD_MCP_DEV=1 to capture MCP session logs for debugging. See CHANGELOG v2.2.3 for details.
Logging (~/.kicad-mcp/logs/):
Logs default to INFO and the file is size-capped so it can't grow without bound. Tune via the MCP server's environment:
| Variable | Default | Purpose |
|---|
LOG_LEVEL / KICAD_MCP_LOG_LEVEL | info | Log verbosity (error/warn/info/debug, or off). KICAD_MCP_LOG_LEVEL wins. |
KICAD_MCP_LOG_MAX_BYTES | 10485760 (10 MB) | Max size per log file before it rotates; 0 disables rotation. |
KICAD_MCP_LOG_BACKUP_COUNT | 3 | Number of rotated backups to keep. |
KICAD_MCP_DEBUG_SKIP | unset | Set to 1 to re-enable the verbose kicad-skip parser DEBUG logs (muted by default). |
See ROADMAP.md for planned features.
What Do You Want to See Next?
We are actively developing new features. Your feedback directly shapes development priorities.
Share your ideas:
- Open a feature request
- Join the discussion
- Star the repo if you find it useful
Contributing
Contributions are welcome! Please follow these guidelines:
- Report Bugs: Open an issue with reproduction steps
- Suggest Features: Describe use case and expected behavior
- Submit Pull Requests:
- Fork the repository
- Create a feature branch
- Follow existing code style
- Add tests for new functionality
- Update documentation
- Submit PR with clear description
See CONTRIBUTING.md for detailed guidelines.
License
This project is licensed under the MIT License. See LICENSE for details.
Acknowledgments
Community Contributors
- @Kletternaut - Routing/component tools, footprint/symbol creators, passthrough workflow, template fixes (PRs #44, #48, #49, #51, #53, #57, #59)
- @Mehanik - Schematic inspection/editing tools, component field positions (PRs #60, #66, #67)
- @jflaflamme - Freerouting autorouter integration with Docker/Podman support (PR #68)
- @l3wi - Local symbol library search, JLCPCB third-party library support (PR #25)
- @gwall-ceres - MCP protocol compliance, Windows compatibility (PR #10)
- @fariouche - Bug fixes (PR #17)
- @shuofengzhang - XDG relative path handling (PR #58)
- @sid115 - Windows setup script improvements (PR #13)
- @pasrom - MCP server bug fixes (PR #50)
Citation
If you use this project in your research or publication, please cite:
@software{kicad_mcp_server,
title = {KiCAD MCP Server: AI-Assisted PCB Design},
author = {mixelpixx},
year = {2025},
url = {https://github.com/mixelpixx/KiCAD-MCP-Server},
version = {2.3.0}
}