CircuitForge — Agentic KiCad MCP Server

Schematic → layout → route → validate → manufacture, with sourcing-awareness, footprint verification, mechanical guardrails, and a self-healing DRC/ERC loop.

CircuitForge is a Model Context Protocol server that lets an agent (Claude Desktop, Claude Code, Cline) design PCBs in KiCad end-to-end. It targets KiCad 9.x and 10.x and is built and verified against KiCad 10.0.3.

Why a three-plane orchestrator

KiCad 9's IPC API only covers the PCB editor and cannot export files, so no single interface does everything. CircuitForge splits the work across three planes:

Plane	Responsibility	Mechanism
File plane	Schematic authoring (.kicad_sch), board files	own round-trip-safe S-expression layer
Live plane	PCB editing on a running KiCad — placement, tracks, vias, zones	IPC API via kicad-python (kipy)
CLI plane	ERC / DRC / netlist / all exports	kicad-cli subprocess

Schematic edits happen on disk; the running PCB instance is told to reload after sync. Every tool returns {status, data, warnings[], errors[]} and never reports success while errors remain.

Status: what actually works here

Run forge_doctor and forge_capabilities to get the live picture. The static maturity is VERIFIED / PARTIAL / STUB per tool (see circuitforge/capability.py). Highlights, all exercised against KiCad 10.0.3 by the test suite:

• Schematic engine (VERIFIED). Authors a .kicad_sch from scratch — embeds symbol definitions, computes pin geometry, snaps nets to pins, drives power rails — that passes kicad-cli sch erc with zero errors and zero warnings, and exports a correct netlist.
• S-expression layer (VERIFIED). Round-trips the real KiCad 10 Device.kicad_sym (100k+ lines), power.kicad_sym, and full schematics with structural equality.
• Self-healing loop (VERIFIED). repair_run runs a bounded ERC/DRC repair loop; on the demo board it converges 2 ERC errors → 0 in one iteration. Never infinite-loops; always reports residual + a per-iteration diff.
• Sourcing (PARTIAL, live). Keyless jlcsearch fallback returns real stock/price/tier; SQLite-cached with a TTL. Official JLCPCB/LCSC clients activate when keys are set.
• Footprint + mechanical verification (VERIFIED). Pad/pitch/courtyard/pin-1/ 3D checks against real .kicad_mod; board-edge / connector-edge / height / RF keepout geometry.
• Board creation (PARTIAL). pcb_create writes a valid 2/4/6-layer board (correct KiCad 9/10 layer numbering) that kicad-cli pcb drc loads cleanly.
• DFM gate (PARTIAL). export_manufacturing_package refuses to emit Gerbers until ERC/DRC/sourcing are green.
• Live plane & routing (STUB→works with deps). Real kipy IPC and Freerouting (Docker/JAR) code paths that degrade to clear, structured stubs when KiCad isn't running / Java/Docker absent — they never crash the agent.

Install

# from this directory
pip install -e .            # or: uvx --from . circuitforge-mcp
# optional: live plane (PCB editing on a running KiCad)
pip install kicad-python

CircuitForge's only hard dependency is mcp. KiCad, Java/Docker, and sourcing keys are discovered at runtime.

MCP client config

{
  "servers": {
    "circuitforge": {
      "type": "stdio",
      "command": "circuitforge-mcp",
      "env": {
        "KICAD_MCP_PROJECT_DIR": "/abs/path/project",
        "KICAD_MCP_PROFILE": "agent_full",
        "KICAD_CLI": "/Applications/KiCad.app/Contents/MacOS/kicad-cli",
        "JLCPCB_API_KEY": "...",      // optional
        "LCSC_API_KEY": "...",        // optional
        "FREEROUTING_MODE": "docker"  // docker | jar | off
      }
    }
  }
}

Profiles

session_set_profile / KICAD_MCP_PROFILE selects which tool groups load: schematic_only (28 tools), pcb_only, manufacturing, agent_full (51).

Quick agent flow

forge_doctor()                       → confirm environment
project_create(path, name, layers=2)
sch_create()
sch_add_symbol("Device:R", "R1", 101.6, 101.6, value="330")
sch_add_symbol("Device:LED", "D1", 101.6, 119.38, value="RED")
sch_connect("+3V3", ["R1.1"]); sch_connect("MID", ["R1.2","D1.2"]); sch_connect("GND", ["D1.1"])
sch_run_erc()                        → reports undriven rails
repair_run("erc")                    → converges to clean
sch_get_netlist()
source_check_bom(components)         → stock / DNP / extended guard
export_manufacturing_package()       → DFM-gated bundle

Tool surface

Grouped by plane (section 6 of the PRD): project_*, txn_*, sch_*, pcb_*, route_*, netclass_define, source_*, bom_cost, verify_footprint, verify_mechanical, validate_drc, repair_run, block_*, export_*, plus forge_doctor / forge_capabilities.

Testing

PYTHONPATH=src python -m pytest        # 84 tests

Tests that need kicad-cli (ERC/DRC/netlist/board-load) auto-skip if KiCad is absent; sourcing tests use recorded fixtures and never hit the network.

Setup you may still need to do

• Install KiCad 9/10 (provides kicad-cli). Already detected here.
• For the live plane: pip install kicad-python, then in KiCad enable Preferences → Plugins → API server and keep KiCad open.
• For Freerouting: Docker (default) or a Java 21 runtime + FREEROUTING_JAR.
• For official sourcing APIs: set JLCPCB_API_KEY / LCSC_API_KEY (the keyless jlcsearch fallback works without them).

Owner: Rishabh / Impetus AI LLC.