{ "markdown": "
\n\n

KiCad MCP Pro

\n\n

\n Drive KiCad schematic, PCB, DRC/ERC, DFM, and manufacturing review from any MCP-capable AI agent.\n

\n\n

\n Documentation ·\n Installation ·\n Quick Start ·\n Tool Reference ·\n AI Agent Setup ·\n AI discovery\n

\n\n

\n \"PyPI\n \"npm\n \"Python\n \"MIT\n \"DOI\"\n

\n\n

\n \"CI\"\n \"GUI\n \"CodeQL\"\n \"OpenSSF\n \"OpenSSF\n

\n\n

\n \"PyPI\n \"npm\n

\n\n\n[![KiCad programmatic parity](https://img.shields.io/badge/KiCad_programmatic_parity-76.6%25-green)](docs/compatibility/capability-parity.generated.md)\n\n\n

\n \"Buy\n

\n\n
\n\n\n\nKiCad MCP Pro is a Model Context Protocol server for KiCad EDA workflows. It exposes tools, resources, and prompts for schematic, PCB, validation, DFM, and manufacturing export automation.\n\nThe server now starts with the bounded `default` profile: 24 read-only review tools instead of the complete expert catalog. Use `build` with write mode for controlled edits, `release` with manufacturing mode for human-gated handoff, or `expert`/`full` only for advanced trusted clients. Current catalog counts and context-size estimates come from [`docs/evidence/progressive-disclosure-profile-snapshot.json`](docs/evidence/progressive-disclosure-profile-snapshot.json); see [`docs/agents/progressive-disclosure.md`](docs/agents/progressive-disclosure.md).\n\nTelemetry and error reporting are disabled by default. Opt-in OpenTelemetry\nconfiguration is documented in\n[`docs/configuration.md`](docs/configuration.md#opentelemetry), and privacy rules\nare documented in [`docs/privacy.md`](docs/privacy.md).\n\n## Scope and honesty\n\nKiCad MCP Pro is a **professional first-pass design and review assistant**, not an\nautomated sign-off authority. ERC/DRC and the export pipeline drive KiCad's own\nengines. The signal-integrity, power-integrity, EMC, and thermal tools are\n**first-order, closed-form estimates** (typically ~5–10% accuracy) — fast first-pass\nreview, **not** a substitute for a 2D/3D field solver, EM/FEA simulation, or formal\nsign-off. Live component sourcing uses the JLCPCB public catalog by default; Nexar,\nDigiKey, and Mouser are available only when their API credentials are configured. What\nfraction of KiCad's programmatic surface the server drives is tracked openly in the\n[capability-parity matrix](docs/compatibility/capability-parity.generated.md). Raw tool count and\ncapability coverage are inventory metrics, not the headline product-quality measure. End-to-end\ntask outcome, mutation recovery, corruption, required DRC execution, and manufacturing\nreproducibility are the outcome KPIs. The committed\n[native-live example evidence](docs/evidence/task-outcomes/2026-08-28-native-live-example/)\nintentionally reports `insufficient_evidence`; representative-corpus target attainment remains\nseparate until the qualification work in #730 is complete.\n\n## Project identity\n\n| Field | Value |\n| --- | --- |\n| Canonical repository | [`oaslananka/kicad-mcp-pro`](https://github.com/oaslananka/kicad-mcp-pro) |\n| PyPI package | [`kicad-mcp-pro`](https://pypi.org/project/kicad-mcp-pro/) |\n| npm wrapper | [`kicad-mcp-pro`](https://www.npmjs.com/package/kicad-mcp-pro) |\n| MCP Registry name | `io.github.oaslananka/kicad-mcp-pro` |\n| Version | `3.34.0` | \n| OSS maturity report | [`docs/repo-maturity-report.md`](docs/repo-maturity-report.md) |\n| OpenSSF evidence | [`docs/openssf-evidence.md`](docs/openssf-evidence.md) |\n\n## Quick Start\n\n### Desktop App\n\nDownload the latest installer from the\n[GitHub releases page](https://github.com/oaslananka/kicad-mcp-pro/releases).\nThe Tauri desktop app starts the Python dashboard server automatically and opens\nthe GUI at `http://127.0.0.1:3334/ui`. Desktop releases launch the matching exact\nbackend version and verify its desktop compatibility handshake before use; see\n[Installation](docs/installation.md#desktopbackend-compatibility).\n\n### CLI\n\n```bash\nuvx kicad-mcp-pro init\nuvx kicad-mcp-pro tray\nuvx kicad-mcp-pro dashboard --open\nuvx kicad-mcp-pro --transport streamable-http --port 3334\n```\n\n### Web Dashboard\n\n```bash\nuvx kicad-mcp-pro dashboard --host 127.0.0.1 --port 3334 --open\n# http://127.0.0.1:3334/ui\n```\n\n## Documentation\n\nThe documentation is organized from setup to operation:\n\n1. [Installation](docs/installation.md)\n2. [Client configuration](docs/client-configuration.md)\n3. [Runtime configuration](docs/configuration.md)\n4. [Tool reference](docs/tools-reference.md)\n5. [Workflows](docs/workflows/first-pcb.md)\n6. [Release process](docs/release-process.md)\n7. [Security and privacy](docs/security/threat-model.md)\n8. [KiCad capability parity](docs/compatibility/capability-parity.generated.md) — how much of KiCad's programmatic surface this server drives\n9. [Error code catalog](docs/errors.md) — stable error codes, retry classes, and recovery\n10. [Work-order audit](docs/status/work-order-audit-2026-06-17.md) — current status of the hardening work order\n\nThe `kicad_capability_parity()` tool reports, per workflow domain, what fraction of\nKiCad's programmatically reachable surface this server can drive (currently **76.3%**),\nkeeping genuine `gap`s distinct from `gui-only-no-api` items that KiCad exposes no\nheadless API for.\n\nThe published documentation site is available at\n[https://oaslananka.github.io/kicad-mcp-pro/](https://oaslananka.github.io/kicad-mcp-pro/).\n\n## Transports\n\nKiCad MCP Pro supports `stdio` and Streamable HTTP. Streamable HTTP is served at\n`/mcp` by default and can be moved with `KICAD_MCP_MOUNT_PATH`.\n\n```bash\nuvx kicad-mcp-pro --transport streamable-http --host 127.0.0.1 --port 3334\n```\n\nStreamable HTTP clients must send:\n\n- `Accept: application/json, text/event-stream`\n- `Content-Type: application/json`\n- `MCP-Protocol-Version: 2025-11-25` after initialization\n- `MCP-Session-Id` on follow-up requests when `KICAD_MCP_STATEFUL_HTTP=1`\n\nBy default Streamable HTTP is stateless, so ChatGPT-style connectors can\ninitialize and call `tools/list` without a session-header injection proxy. Set\n`KICAD_MCP_STATEFUL_HTTP=1` to require session IDs after `initialize`.\n\nThe deprecated HTTP+SSE fallback routes are disabled by default. Set\n`KICAD_MCP_LEGACY_SSE=1` only for older clients that cannot use Streamable HTTP.\n\n## Install\n\nPublished packages:\n\n```bash\nuvx kicad-mcp-pro --help\nnpx kicad-mcp-pro --help\n```\n\nFresh source checkout on supported Linux hosts:\n\n```bash\n./scripts/bootstrap-dev.sh\nsource .dev-env.sh\npnpm run dev:doctor -- --ci\n```\n\nThe repository bootstrap installs checksum-pinned Python, uv/uvx, Node.js,\npnpm, Task, and Rust tooling into ignored checkout-local roots and performs\nfrozen dependency installation. It does not modify global tool directories.\nSee the [reproducible bootstrap guide](docs/development/reproducible-bootstrap.md)\nfor `--core-only`, `--check`, cleanup, upgrade, and KiCad capability modes.\n\n## Package metadata\n\nThe canonical metadata inputs are `pyproject.toml` for package version and repository identity, and `compatibility.yaml` for KiCad and MCP support policy. `server.json` is the generated registry manifest. `pnpm run metadata:sync` renders the public surfaces, and `pnpm run metadata:check` verifies them in CI and release validation.\n\n## Usage\n\nUse `kicad-mcp-pro --help` to inspect CLI commands and\n[`docs/client-configuration.md`](docs/client-configuration.md) to configure an\nMCP client. The generated tool catalog is available in\n[`docs/tools-reference.generated.md`](docs/tools-reference.generated.md).\n\n\n## Agent plugin and skills\n\nThis repository owns the product-level agent plugin and KiCad-specific skills for\nKiCad MCP Pro. The central [`agent-tools`](https://github.com/oaslananka/agent-tools)\nrepository should catalog this plugin, but the manifest and workflow instructions live\nhere so they stay synchronized with the actual MCP server tools.\n\n| File | Purpose |\n| --- | --- |\n| [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json) | Product-level plugin manifest for compatible agent runtimes and marketplace catalogs. |\n| [`.mcp.json`](.mcp.json) | Claude Code project-local MCP server configuration. |\n| [`.codex/config.example.toml`](.codex/config.example.toml) | Codex CLI MCP configuration example. |\n| [`.vscode/mcp.example.json`](.vscode/mcp.example.json) | VS Code / GitHub Copilot workspace MCP configuration example. |\n| [`opencode.example.jsonc`](opencode.example.jsonc) | OpenCode project MCP configuration example. |\n| [`.opencode/skills/`](.opencode/skills) | OpenCode-native mirrored skill definitions. |\n| [`docs/agent-runtime-config.md`](docs/agent-runtime-config.md) | Agent runtime setup and validation matrix. |\n| [`skills/kicad-design-review/SKILL.md`](skills/kicad-design-review/SKILL.md) | Comprehensive KiCad design review skill. |\n| [`skills/pcb-design/SKILL.md`](skills/pcb-design/SKILL.md) | PCB design, layout inspection, placement, routing, stackup, and board-quality workflow. |\n| [`skills/drc-check/SKILL.md`](skills/drc-check/SKILL.md) | ERC/DRC execution, triage, waiver review, and revalidation workflow. |\n| [`skills/fabrication-output/SKILL.md`](skills/fabrication-output/SKILL.md) | Manufacturing export, DFM, release evidence, and fabrication-package workflow. |\n| [`skills/schematic-review/SKILL.md`](skills/schematic-review/SKILL.md) | Schematic inspection, ERC, connectivity, power, symbol, and readability workflow. |\n\n### Agent setup\n\nKiCad MCP Pro can be launched with the published Python package, npm wrapper, or the\ncontainer metadata declared in [`server.json`](server.json). Common local starts are:\n\n```bash\nuvx kicad-mcp-pro --transport stdio\nuvx kicad-mcp-pro --transport streamable-http --host 127.0.0.1 --port 3334\nnpx kicad-mcp-pro --help\n```\n\nFor source checkouts, run the normal repository validation path before publishing plugin\nchanges:\n\n```bash\ncorepack pnpm run metadata:check\npython3 -m json.tool .claude-plugin/plugin.json >/dev/null\n```\n\n### Validation workflow\n\nBefore listing this plugin as active from `agent-tools`, verify at least one compatible\nagent runtime can:\n\n1. Discover `.claude-plugin/plugin.json`.\n2. Launch or connect to `kicad-mcp-pro` over `stdio` or Streamable HTTP.\n3. Call `kicad_get_server_info` or `kicad_get_project_info`.\n4. Load a skill from `skills/` and follow the workflow without referencing missing tools.\n5. Report ERC, DRC, DFM, export artifacts, assumptions, and human-review requirements\n separately.\n\nKiCad MCP Pro is an engineering assistant, not an autonomous manufacturing sign-off\nauthority. Generated PCB and fabrication outputs require qualified human review before\nfabrication or assembly.\n\n## Development\n\nNew contributors should start with [`ARCHITECTURE.md`](ARCHITECTURE.md), which maps\nthe five layers (transport → MCP protocol → orchestration → KiCad adapter seam →\npure domain) and shows exactly how to add a new tool. The runtime model and\nquality-gate stack are documented in\n[`docs/development/architecture.md`](docs/development/architecture.md).\n\nThe project uses a `Taskfile.yml` for common development commands. After\ncloning the repository:\n\n```bash\ntask install # Install all dependencies (pnpm + uv)\ntask verify # Run the local quality gate: lint → format → typecheck → test → build\ntask test # Run unit tests only\ntask lint # Run lint and metadata checks\ntask format # Auto-format the codebase\ntask typecheck # Run strict static type checking\ntask build # Build release artifacts\ntask ci # Run the local equivalent of the full CI pipeline\ntask hooks # Install local git hooks\n```\n\nAll changes must pass `task verify` before opening a pull request.\n\n## Contributing\n\nRead [`CONTRIBUTING.md`](CONTRIBUTING.md) before opening a pull request. All\nchanges must pass the repository's format, lint, type-check, test, workflow,\nsecurity, and package metadata gates.\n\n## Cite this software\n\nIf you use KiCad MCP Pro in research or a technical publication, cite the\narchived release via its DOI (see [`CITATION.cff`](CITATION.cff) for full\nmetadata):\n\n```bibtex\n@software{aslan_kicad_mcp_pro,\n author = {Aslan, Osman},\n title = {KiCad MCP Pro},\n license = {MIT},\n url = {https://github.com/oaslananka/kicad-mcp-pro},\n doi = {10.5281/zenodo.21283791}\n}\n```\n\nEvery GitHub release is archived on Zenodo under this concept DOI, which\nalways resolves to the most recent version.\n\n## License\n\nKiCad MCP Pro is available under the [MIT License](LICENSE).\n", "bytes": 14888, "sha": "6be2019b0c39bc03a7289b066306397b9f285483e2630bdd48537547d1400cc8", "repo_slug": "oaslananka/kicad-mcp-pro", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_oaslananka_kicad_mcp_pro_eb219851/readme" }