dcc-mcp-kicad

Typed DCC-MCP adapter for KiCad 9 headless PCB files, using the installed native pcbnew Python API and kicad-cli. This service owns an isolated board; it does not connect to PCB Editor, manipulate an open board, or provide IPC/UI control.

Install and start

Use a Python interpreter that can import the KiCad 9 pcbnew module. On Debian-based Linux the distribution's /usr/bin/python3 is often required:

/usr/bin/python3 -m venv --system-site-packages .venv
.venv/bin/python -m pip install .
mkdir -p workspace
DCC_MCP_GATEWAY_PORT=0 .venv/bin/dcc-mcp-kicad --workspace "$PWD/workspace"

Python 3.10+ is declared because this adapter targets the KiCad 9 runtime rather than the organization's older embedded-Python LTS profile. No Python 3.7 support or release qualification is claimed. This candidate pins Core and server to 0.20.41. The native KiCad 9.0.2/Linux acceptance recorded for 0.20.39 is historical; it does not qualify the upgraded runtime. See the runtime upgrade and rollback record for the new verification scope and remaining gates.

Workspace is mandatory (--workspace or DCC_MCP_KICAD_WORKSPACE). Port defaults to an OS-assigned loopback port, printed as mcp_url in a JSON readiness line. Connect a direct MCP client to that URL. The optional shared gateway is disabled by default. Set --port or DCC_MCP_KICAD_PORT only when a fixed endpoint is required. Core owns MCP; this adapter adds no external network service or independent gateway.

Related MCP server: CDT-KiCAD

Tools and workflow

Search/load skill kicad-board, then use:

• status: native version, lane identity, workspace and board state

• create_board: bounded 20–200 mm synthetic test board with two test points

• create_sensor_carrier: bounded 70–100 × 45–70 mm concept with four M3 holes, seven synthetic component footprints, five nets, partial routes and silkscreen; deliberately not electrically validated or a fabrication design

• inspect_board: item counts, stable track UUIDs and widths

• set_track_width: one UUID-selected straight track, 0.1–3 mm

• save_board: atomic save, native reopen, state comparison and SHA-256

• open_board: load an existing workspace .kicad_pcb

• export_svg: current snapshot's front copper, silkscreen and outline

• run_drc: native JSON DRC report and counts, including actual violations

All native tools use main affinity and in-process Core dispatch. Save/open/export/ DRC are async monolithic jobs: retain the returned job ID and poll Core jobs_get_status to terminal completion. Never blindly repeat after a timeout.

The nine adapter tools add no arbitrary script execution. Core also exposes its own admin/introspection tools, so this endpoint is for trusted local clients only. Existing output needs overwrite=true; unsaved session state needs discard_unsaved=true before replacement. Paths are resolved against a single explicit root and reject traversal and all symlinks beneath the workspace. Do not grant the workspace to untrusted users who can concurrently replace its path components. This is a local trusted-workspace boundary, not an OS sandbox.

DRC results are diagnostics, not electrical or manufacturing certification. Schematic editing, ERC, live IPC, autorouting, project configuration, production fabrication outputs and GUI behavior are outside version 0.1 scope.

See architecture, validation, and installation details. No package release is automated.

Concurrency and recovery

Use expected_revision from status/inspection on edits and outputs to reject stale work. Saving rechecks the loaded file's SHA-256 after staging and before publication; detected external changes or deletion fail closed. Reopen and reconcile it first. Pause external writers during saving: the final check and replacement are separate filesystem operations. Stopped server objects cannot be reused; create a new server instance or restart the process. The complete native/MCP gate is described in validation, including the official MCP Python SDK check.