codex-kicad-mcp
A safe, read-first Model Context Protocol
server for KiCad workflows. It discovers KiCad projects, parses schematics and
PCBs into structured data, and runs ERC/DRC checks through kicad-cli without
editing design files. MCP resources expose the same data through stable URIs,
prompts provide structured task instructions, and an opt-in write API performs
snapshot-backed, audited minimal edits.
Install
uv pip install codex-kicad-mcp
Or from a source checkout:
cd mcp
uv pip install -e ".[dev]"
Run
Set KICAD_WORKSPACE to the directory that contains your .kicad_pro
projects, then start the stdio server:
$env:KICAD_WORKSPACE = "C:/path/to/eda-workspace"
codex-kicad-mcp
Every tool resolves paths below KICAD_WORKSPACE; attempts to escape fail
before any file access or command runs. See
docs/security-model.md for the full trust
boundaries.
Tools
| Tool | Reads | KiCad required |
|---|---|---|
kicad_cli_version |
CLI version | Yes |
list_kicad_projects |
Workspace tree | No |
inspect_project |
Project file inventory | No |
project_summary |
Project JSON and inventory | No |
read_schematic |
Schematic S-expression | No |
read_pcb |
PCB S-expression | No |
read_hierarchy |
Sheet hierarchy and pins | No |
read_buses |
Bus geometry and entries | No |
read_netlist |
Netlist CLI export | Yes |
read_bom |
BOM CLI export | Yes |
read_board_metrics |
Board size and copper totals | No |
read_layer_stackup |
Stackup or layer table | No |
read_zones |
Copper zones and polygons | No |
read_vias |
Vias and layer pairs | No |
run_kicad_cli_check |
Structured ERC/DRC JSON | Yes |
analyze_power_rails |
Netlist power topology | Yes |
check_decoupling |
Netlist and PCB capacitor placement | Yes |
cross_probe |
Schematic, netlist, and PCB matches | Yes |
compare_schematic_pcb |
Netlist-to-PCB parity | Yes |
run_design_review |
Unified review findings | Yes |
analyze_signal_integrity |
PCB routing geometry | No |
analyze_board_density |
PCB occupancy metrics | No |
check_fabrication_readiness |
PCB manufacturing readiness | No |
preview_write |
Dry-run edit plan (opt-in) | No |
confirm_write |
Execute previewed edit (opt-in) | No |
rollback_snapshot |
Restore snapshot files (opt-in) | No |
list_snapshots |
Write snapshot inventory (opt-in) | No |
get_write_audit |
Append-only audit log (opt-in) | No |
Write tools are inert unless KICAD_ENABLE_WRITES=1 is set exactly; see
docs/tool-reference.md for the preview →
confirm pipeline, token binding, and audit record shape.
Resources
Nine resources under codex-kicad://projects/{project}/… mirror the read
tools: manifest, raw (suffix allowlist, size-bounded), schematic, pcb,
hierarchy, netlist, bom, stackup, and report (normalized local
ERC/DRC JSON). The {project} parameter is the percent-encoded
workspace-relative .kicad_pro path.
Prompts
Seven prompts render structured task instructions (never writes):
audit_project, generate_bom_report, review_power_distribution,
review_signal_integrity, cross_probe_issue, prepare_fabrication, and
summarize_project_for_handoff.
Configuration
All limits are read at call time; invalid values raise a tool error instead of being clamped.
| Variable | Default | Purpose |
|---|---|---|
KICAD_WORKSPACE |
— (required) | Root directory for all project paths |
KICAD_MAX_FILE_BYTES |
33554432 | Largest artifact accepted for parsing |
KICAD_MAX_SEXPR_TOKENS |
1000000 | S-expression token budget |
KICAD_MAX_SEXPR_DEPTH |
512 | S-expression nesting budget |
KICAD_MAX_RESULT_ITEMS |
100000 | Item cap per response |
KICAD_MAX_CLI_OUTPUT_BYTES |
1048576 | CLI stdout/stderr cap per response |
KICAD_CLI_VERSION_TIMEOUT |
15 | Seconds for kicad-cli --version |
KICAD_CLI_CHECK_TIMEOUT |
120 | Seconds for an ERC/DRC check |
KICAD_EXPORT_TIMEOUT |
120 | Seconds for a netlist or BOM export |
KICAD_ENABLE_WRITES |
unset (writes off) | Set exactly 1 to enable the write API |
KICAD_SNAPSHOT_ROOT |
<workspace>/.kicad-mcp-snapshots |
Directory for write snapshots and audit log |
KICAD_WRITE_TOKEN_TTL |
900 | Confirm-token lifetime in seconds |
KICAD_WRITE_PREVIEW_TTL |
1800 | Preview plan lifetime in seconds |
KICAD_MAX_SNAPSHOTS_LISTED |
50 | Cap on list_snapshots results |
The complete tool contract lives in
docs/tool-reference.md.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file codex_kicad_mcp-0.2.0.tar.gz.
File metadata
- Download URL: codex_kicad_mcp-0.2.0.tar.gz
- Upload date:
- Size: 190.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
22b56bceaa6a299d0770b30d234bfc3f360133d94376d1d6434ee865b67ad0f1
|
|
| MD5 |
4f2191b9212db867e7761b021d6801dd
|
|
| BLAKE2b-256 |
63b1f18159386ac282bcc9a2a0909f30212930989ef6e5cd58900e02d4bdd625
|
Provenance
The following attestation bundles were made for codex_kicad_mcp-0.2.0.tar.gz:
Publisher:
validate.yml on w23x0/codex-kicad-mcp
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
codex_kicad_mcp-0.2.0.tar.gz -
Subject digest:
22b56bceaa6a299d0770b30d234bfc3f360133d94376d1d6434ee865b67ad0f1 - Sigstore transparency entry: 2751247156
- Sigstore integration time:
-
Permalink:
w23x0/codex-kicad-mcp@568c713cb095ff17fffe646af404e14932daf5bd -
Branch / Tag:
refs/tags/v0.2.0 - Owner: https://github.com/w23x0
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
validate.yml@568c713cb095ff17fffe646af404e14932daf5bd -
Trigger Event:
push
-
Statement type:
File details
Details for the file codex_kicad_mcp-0.2.0-py3-none-any.whl.
File metadata
- Download URL: codex_kicad_mcp-0.2.0-py3-none-any.whl
- Upload date:
- Size: 74.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
57af44670a02cfecfc4ba442cde96bbd9f6151386959c91acf9aad7cb116ad9c
|
|
| MD5 |
e49a5ac7e23690bf0625e1aaf893f00c
|
|
| BLAKE2b-256 |
2432e2fef379d15f67779625ba143317516e50986bb21fd6c5f14953e45033cc
|
Provenance
The following attestation bundles were made for codex_kicad_mcp-0.2.0-py3-none-any.whl:
Publisher:
validate.yml on w23x0/codex-kicad-mcp
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
codex_kicad_mcp-0.2.0-py3-none-any.whl -
Subject digest:
57af44670a02cfecfc4ba442cde96bbd9f6151386959c91acf9aad7cb116ad9c - Sigstore transparency entry: 2751247473
- Sigstore integration time:
-
Permalink:
w23x0/codex-kicad-mcp@568c713cb095ff17fffe646af404e14932daf5bd -
Branch / Tag:
refs/tags/v0.2.0 - Owner: https://github.com/w23x0
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
validate.yml@568c713cb095ff17fffe646af404e14932daf5bd -
Trigger Event:
push
-
Statement type:
