kicad-forge
Provides analysis, authoring, and simulation for KiCad projects, including reading and writing schematics and PCBs, component and net analysis, PCB statistics and connectivity checks, netlist verification with kicad-cli, and SPICE netlist generation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@kicad-forge Analyze my schematic for missing power connections."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
kicad-forge
One MCP server for KiCad analysis + authoring + simulation. Reads and writes
KiCad files directly as S-expressions, so nothing here needs KiCad installed
except the two things that genuinely do (cross-checking netlists with
kicad-cli, and reading the stock symbol libraries).
Built and tested in one session. 141/141 tests pass — 113 unit, 28 over the live MCP protocol. Read the Honest status section before you trust it with a board you are paying to fabricate.
Install
git clone https://github.com/mpeyal/kicad-forge.git
cd kicad-forge
pip install mcpThat is the only dependency. Everything else is the standard library.
Register with Claude Desktop — %APPDATA%\Claude\claude_desktop_config.json:
{
"mcpServers": {
"kicad-forge": {
"command": "C:\\Program Files\\KiCad\\10.0\\bin\\python.exe",
"args": ["C:\\path\\to\\kicad-forge\\run_server.py"]
}
}
}Using KiCad's bundled Python is recommended but not required — it is not
needed for parsing (this server never imports pcbnew), but it guarantees
kicad-cli is on PATH for verify_netlist. Any Python 3.10+ works.
Claude Code:
claude mcp add kicad-forge -s user -- python -m kicad_forge.serverIf Claude Desktop came from the Microsoft Store, %APPDATA% is
virtualised and the config is NOT at AppData\Roaming\Claude\. It lives at:
%LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\claude_desktop_config.jsonEditing the non-packaged path appears to work and silently does nothing —
no server, and no log file to tell you why. If you add an entry and no
mcp-server-<name>.log ever appears in %LOCALAPPDATA%\Claude\Logs, you
are editing the wrong file.
Verify: ask "what are kicad-forge's capabilities?" — the capabilities tool
reports the version, whether KiCad's symbol libraries were found, whether a
SPICE engine was found, and the full coverage manifest.
Related MCP server: mcp-kicad-cli
The 18 tools
Analysis
Tool | Does |
| Full review: components, nets, analog/digital checks, PCB routing, DFM |
| Components with prefix/value filters |
| Netlist derived geometrically from the files |
| Every connection from a component or one pin |
| Diffs our netlist against |
PCB
Tool | Does |
| Layers, dimensions, footprints, tracks, vias, zones |
| Union-find copper graph: routed / unrouted / islanded nets |
| Footprints, filterable by board side |
Authoring (atomic writes)
Tool | Does |
|
|
| Place a symbol from KiCad's libraries or the built-in set |
| Rectangular IC from a pin list, for parts in no library |
| Wires and local/global/hierarchical labels |
| Exact pin coordinates, so wires land on pins |
Simulation
Tool | Does |
| SPICE netlist; active devices are skipped, never guessed |
| Auto-generates testbenches, runs them, compares to analytics |
| Run an arbitrary deck |
Write safety
You asked for no safety layer, and there is none: no dry-run gating, no .bak
files, no confirmation prompts. Writes go straight through.
What is kept, because it is the absence of a bug rather than a safety feature:
Atomic replace. Serialise to a temp file in the same directory →
fsync→os.replace()(atomic on Windows and POSIX). A crash mid-write leaves the original file untouched instead of truncated.Verify before replace. The serialised bytes are re-parsed and compared to the source tree. A mismatch raises and writes nothing.
Atom text is preserved verbatim.
1.270000stays1.270000;0.1stays0.1. Numbers are never round-tripped throughfloat()and reformatted.
That last point is why the round-trip is byte-identical on real KiCad files — your git diffs show only what actually changed.
Still: keep your projects in git. Nothing above protects you from a logic bug.
Honest status
Verified
Verified against real LTspice 24.1.9. Decks generated by this tool were executed by LTspice on Windows:
Testbench
Analytical
LTspice
Error
RC low-pass 10k/100n
159.154943092 Hz
159.154943622 Hz
3.3e-7 %
Divider 100k/100k
0.500000000 V
0.500000000 V
0 %
The LTspice
.logfiles are checked in undertests/fixtures/ltspice/and asserted on every run.100% agreement with KiCad's own netlist exporter. A 24-component ESP32 board was generated by this tool, opened in Eeschema 10.0.5, and its netlist exported by KiCad. All 18 nets match exactly — same pin membership, same net names, zero missing, zero invented. KiCad's
.netfile is checked in astests/fixtures/esp32_sensor_kicad_reference.netand is asserted against on every test run.Byte-identical round trip on real KiCad 9
.kicad_schand.kicad_pcb.Known-answer detector maths, hand-computed and asserted exactly: regulator Vout 5.1956 V, divider ratio 0.153976, RC cutoff 159.1549 Hz, I²C rise time 398.2 ns.
55 component-value spellings (
4k7,1R0,2u2,100nF/50V,1uF 0805,4.7 kOhm, …).Pin geometry against hand-computed transforms at 0/90/180/270° and both mirrors; all pins land on KiCad's 1.27 mm grid.
Cross-validated with
kiutils, an independent third-party parser: it reads the schematics this tool writes and agrees on the component set.28 checks over the real MCP protocol — subprocess, stdio, handshake,
tools/list,tools/call.
Not verified
No large-corpus validation. kicad-happy is regression-tested against 5,800+ real projects. This has been checked against one real KiCad-exported netlist, two real KiCad files, and fixtures it generated itself. Expect format edge cases on real-world boards — run
verify_netliston your own designs, which is exactly what it is for.PCB authoring is not implemented. Only project scaffolding and board outline. No footprint placement, no routing, no Gerber export.
Deliberately not implemented
detectors.COVERAGE lists this in the tool output too, so the model using the
server sees it rather than reading an empty findings list as a clean board:
EMC / radiated emissions · thermal / junction temperature · component lifecycle & EOL · MPN sourcing · voltage derating · signal integrity & impedance · differential-pair skew · datasheet extraction · power sequencing · Gerber verification.
An empty findings list is not a clean bill of health. For those domains use kicad-happy, which implements them properly.
Known limitations
I²C detection is name-based; a bus with unconventional net names is missed.
Divider detection is topological — it reports voltage-sensing dividers too.
RC filter detection requires the cap's far side to be ground.
PCB pad/track contact uses bounding boxes; rotated non-rectangular pads are approximated.
Arc tracks are measured by their chord, so arc-heavy boards under-report total track length.
The
VREF_TABLEcovers 28 regulators. Unknown parts reportneeds-datarather than guessing a Vref.
Where this fits
It does not replace kicad-happy — that has 61 detectors and a 5,800-project
regression corpus, and this does not. What this adds is the combination you
asked for in one server: authoring and simulation and analysis, with no
pcbnew/SWIG dependency and no KiCad required for the read path.
A reasonable split: this for authoring and netlist/SPICE work, kicad-happy for the review pass before you order boards.
Tests
python kicad_forge/tests/test_suite.py # 113 unit tests
python kicad_forge/tests/test_mcp_protocol.py # 28 protocol tests
python kicad_forge/tests/make_fixture.py # regenerate the known-answer fixtureMIT.
Available Tools
18 toolsadd_componentB
Add a component to a schematic. Uses the installed KiCad symbol libraries when available, otherwise a built-in symbol set. Writes atomically.
Inputs: x_mm (required), y_mm (required), lib_id (required), schematic_path (required), +4 more. Returns: result
add_generic_icA
Add a generic rectangular IC symbol by pin list. Use when the part is not in any installed library. pins_json: [[number, name, electrical_type], ...]
Inputs: x_mm (required), y_mm (required), lib_id (required), pins_json (required), +4 more. Returns: result
add_labelB
Place a net label. kind is local, global or hierarchical. Local labels join nets within one sheet; global labels join across the design.
Inputs: text (required), x_mm (required), y_mm (required), schematic_path (required), +1 more. Returns: result
add_wireA
Draw a wire between two points (mm, snapped to the 1.27 mm grid).
Inputs: x1_mm (required), x2_mm (required), y1_mm (required), y2_mm (required), +1 more. Returns: result
analyze_projectA
Full review of a KiCad project: components, nets, analog/digital analysis, PCB routing and DFM. Pass a .kicad_sch and optionally a .kicad_pcb.
Inputs: schematic_path (required), pcb_path, follow_hierarchy. Returns: result
capabilitiesA
Report what this server can do, what it deliberately does not do, and which external tools were found.
Inputs: no named parameters. Returns: result
component_pin_positionsB
Report the pin coordinates of a placed component, so wires can be drawn to exactly the right points.
Inputs: reference (required), schematic_path (required). Returns: result
create_kicad_projectB
Create a new KiCad project (.kicad_pro/.kicad_sch/.kicad_pcb), optionally with a board outline.
Inputs: name (required), directory (required), board_width_mm, board_height_mm. Returns: result
export_spice_netlistB
Export a SPICE netlist from the schematic. Active devices are listed as skipped rather than guessed.
Inputs: schematic_path (required), output_path, follow_hierarchy. Returns: result
list_componentsB
List components in a schematic, with optional reference-prefix or value filters.
Inputs: schematic_path (required), prefix, value_contains, follow_hierarchy. Returns: result
list_footprintsA
List PCB footprints, optionally filtered to one side.
Inputs: pcb_path (required), side. Returns: result
list_netsB
Derive the netlist geometrically from the schematic files. Works with no KiCad installed.
Inputs: schematic_path (required), name_contains, follow_hierarchy. Returns: result
pcb_connectivityB
Copper connectivity: which nets are fully routed, unrouted, or split into islands.
Inputs: pcb_path (required). Returns: result
pcb_statisticsC
Board statistics: layers, dimensions, footprints, tracks, vias, zones.
Inputs: pcb_path (required). Returns: result
run_spiceC
Run an arbitrary SPICE deck and return the parsed measurements.
Inputs: deck (required), timeout_s. Returns: result
simulate_subcircuitsC
Generate SPICE testbenches for every subcircuit the detectors found, run them if a simulator is present, and compare simulated against analytical values.
Inputs: schematic_path (required), run, tolerance_pct, follow_hierarchy. Returns: result
trace_connectionsC
Trace every connection from a component, or from one specific pin.
Inputs: reference (required), schematic_path (required), pin, follow_hierarchy. Returns: result
verify_netlistA
Cross-check our geometric net tracing against KiCad's own netlist exporter. Requires KiCad installed. This is the authoritative correctness check.
Inputs: schematic_path (required), follow_hierarchy. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Tools map to distinct actions and resources, so an agent can usually tell list_components from list_nets or pcb_statistics. The slight overlap comes from the SPICE-related tools and analyze_project, which can approach similar territory but are differentiated by purpose and output.
Most tools follow a clear snake_case verb_noun or area_noun pattern: list_*, add_*, pcb_*, simulate_*, run_*. A few names like capabilities and component_pin_positions are noun phrases rather than verb-first actions, but the overall style is consistent enough to navigate.
With 18 tools the server is slightly above the typical well-scoped 3-15 range, but the tool set spans schematic analysis, PCB analysis, project creation, and simulation. Each tool has a distinct job, so the larger count is justified rather than bloated.
The server covers project creation, additive schematic editing, net tracing, PCB statistics/connectivity, and SPICE workflows well. However, it lacks update, remove, or move operations for components, wires, and labels, leaving the editing lifecycle incomplete for a design tool.
Maintenance
Related MCP Connectors
Design, route, check, review and export manufacturable PCBs from plain language; KiCad import.
EasyGerber brings AI printed circuit board (PCB) design, layout, and routing to MCP-compatible assistants. Describe a circuit or start from firmware pin assignments, search published electronic components, and build schematics using catalog parts with their footprints and available 3D models. Create and revise boards, generate layouts with automatic component placement and routing, inspect previews, and check saved layouts for blocking design issues. Export manufacturing ZIPs containing Gerber and drill files, a bill of materials, and component placement data, or download an editable EasyGerber (.egb) file. Start without signing up. Your agent uses one private board reference to create and continue a board, including catalog access, edits, layout, checks, previews, and exports, without a separate guest setup step or token to manage. To keep the board in your account or work with permitted saved personal or organization boards, complete EasyGerber sign-in and OAuth consent, then resume the same task. Account permissions, plan limits, and generation billing apply; support depends on your MCP client and installed integration.
Autonomous 0-DRC PCB Routing, RF/DFM Pre-Flight & KiCad MCP Server (calligraphyeda.com).
Headless CAD engine & MCP server for 2D/3D drafting, solids, DXF/SVG export, and automation.
Related MCP Servers
- AlicenseAqualityAmaintenanceMCP servers for KiCad schematic, PCB, symbol, footprint, and project automation, enabling AI-assisted electronic design via tools for read/write, analysis, and exports.109521 PyPI16GPL 3.0
- AlicenseBqualityDmaintenanceEnables KiCad CLI automation via MCP, providing tools for ERC, DRC, BOM export, netlist export, Gerbers, drill files, STEP, IPC-2581, and GLB output.10Apache 2.0
- AlicenseAqualityCmaintenanceEnables MCP clients such as Claude Code to work on KiCad 10 designs by driving kicad-cli for ERC, DRC, netlists and fabrication exports, KiCad's IPC API for live board editing, and lossless edits of schematic and project files. It also provides design review, routing, parts and datasheet tooling so a board can be treated as data and checked against fab limits.353MIT
- AlicenseNot gradedqualityCmaintenanceProvides read-only MCP tools for parsing KiCad netlists and schematics, running evidence-based audits, and generating deterministic sizing and BOMs.MIT