kicad-pro
KiCad MCP Pro plugin for schematic review, PCB design assistance, DRC/ERC validation, DFM checks, and manufacturing release workflows.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
Its scripts were only partly scanned.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/oaslananka/kicad-mcp-pro with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/oaslananka/kicad-mcp-pro'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/oaslananka--kicad-mcp-pro)HTML
<a href="/listings/oaslananka--kicad-mcp-pro"><img src="/api/listings/oaslananka--kicad-mcp-pro/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Local HTTP and browser dashboard
No desktop installer or Tauri application is required. The Python server retains Streamable HTTP and the browser dashboard. Start the local MCP endpoint:
uvx kicad-mcp-pro --transport streamable-http --host 127.0.0.1 --port 3334
Then connect your MCP client to `http://127.0.0.1:3334/mcp`. To open the owner-only browser dashboard:
uvx kicad-mcp-pro dashboard --host 127.0.0.1 --port 3334 --open
The local server and dashboard work without Cloud sign-in. Cloud access is optional and requires separate authorization for devices and project metadata. See [Installation](docs/installation.md) for setup and security details.
CLI (recommended)
Install the CLI once with [uv](https://docs.astral.sh/uv/concepts/tools/), then use the same command on Windows PowerShell, macOS, or Linux:
uv tool install kicad-mcp-pro kicad-mcp-pro --version kicad-mcp-pro setup kicad-mcp-pro doctor
Optional Cloud remote — Windows
With KiCad MCP Pro installed, open PowerShell and run:
kicad-mcp-pro cloud connect
On first use, choose a local KiCad project and approve the device pairing in your browser. Subsequent starts reuse the paired device and project. The terminal stays open and reports **Connected** only after the Cloud acknowledges the signed session. Connection events, folder selection and device-bound tool calls stream with timestamps and measured durations. Press Ctrl+C to disconnect. Foreground mode stops a verified user-owned background Connector task, avoiding the extra empty Python console window. On the Cloud Devices page, Add project opens the native Windows folder picker; only opaque folder tokens leave your computer. Local KiCad files and absolute project paths remain on-device.
Open the [Cloud Devices page](https://kicad-mcp-pro.oaslananka.dev/devices) and choose **Manage access** for the project to grant/revoke each AI client's **project-summary** permission. Cloud remote editing is not yet available: no write controls are presented as functional. Local MCP use does not require a Cloud account. Selecting a different project on a paired device is not yet supported in this foreground CLI.
**Owner-operated Cloud editing (opt-in, not available on the public Cloud by default):** After a Cloud operator has enabled the signed write service, obtain its **public** Ed25519 issuer key and independently verify the operator-provided SHA-256 SPKI fingerprint. From an interactive Windows terminal, for a device that is already paired, run:
kicad-mcp-pro cloud trust-write-issuer --public-key-file .\issuer-public.pem --sha256 <verified-64-character-SPKI-sha256> kicad-mcp-pro cloud connect --enable-native-write
The key and fingerprint are pinned to the current Windows user's credential store; a different issuer cannot replace them silently. The foreground owner command also checks and prepares the Windows-local replay-protection directory. Neither command gives an AI app access to any design. The AI client must separately request and receive OAuth projects:write consent, then the owner must allow editing for that **specific client and project** in Cloud Devices. Existing clients and projects remain read-only. The write service and real KiCad save/reopen acceptance must be operational before presenting editing as available. Do not enable editing on production designs to validate the feature; use a disposable KiCad test board and verify its independent on-disk state.
`setup` guides the local MCP client configuration without requiring a Cloud account. For scripts, use `kicad-mcp-pro setup --agent claude-code`; the existing `init` and `quickstart` aliases remain supported.
To check for a stable update or safely remove a CLI installation:
kicad-mcp-pro update check kicad-mcp-pro uninstall # If installed with uv, perform the suggested action in your terminal: uv tool upgrade kicad-mcp-pro uv tool uninstall kicad-mcp-pro
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/plugin.json · Manifest · 20 lines
- {
- "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
- "name": "kicad-pro",
- "version": "4.19.0",
- "description": "KiCad MCP Pro plugin for schematic review, PCB design assistance, DRC/ERC validation, DFM checks, and manufacturing release workflows.",
- "mcpServers": "./.mcp.json",
- "skills": [
- "./skills/kicad-design-review",
- "./skills/pcb-design",
- "./skills/drc-check",
- "./skills/fabrication-output",
- "./skills/schematic-review",
- "./skills/visual-excellence",
- "./skills/wired-subcircuit-design"
- ],
- "author": {
- "name": "oaslananka",
- "url": "https://github.com/oaslananka"
- }
- }
README.md · README · 423 lines
- <div align="center">
- <h1>KiCad MCP Pro</h1>
- <p>
- <strong>Drive KiCad schematic, PCB, DRC/ERC, DFM, and manufacturing review from any MCP-capable AI agent.</strong>
- </p>
- <p>
- <a href="https://oaslananka.github.io/kicad-mcp-pro/">Documentation</a> ·
- <a href="docs/installation.md">Installation</a> ·
- <a href="#quick-start">Quick Start</a> ·
- <a href="docs/tools-reference.generated.md">Tool Reference</a> ·
- <a href="https://oaslananka.github.io/kicad-mcp-pro/agents/">AI Agent Setup</a> ·
- <a href="docs/llms.txt">AI discovery</a> ·
- <a href="https://deepwiki.com/oaslananka/kicad-mcp-pro">Ask DeepWiki</a>
- </p>
- <p>
- <a href="https://pypi.org/project/kicad-mcp-pro/"><img src="https://img.shields.io/pypi/v/kicad-mcp-pro?label=pypi" alt="PyPI Version" /></a>
- <a href="https://www.npmjs.com/package/kicad-mcp-pro"><img src="https://img.shields.io/npm/v/kicad-mcp-pro?label=npm" alt="npm Version" /></a>
- <a href="https://pypi.org/project/kicad-mcp-pro/"><img src="https://img.shields.io/pypi/pyversions/kicad-mcp-pro?label=python" alt="Python Version" /></a>
- <a href="https://doi.org/10.5281/zenodo.21283791"><img src="https://zenodo.org/badge/1255527274.svg" alt="DOI" /></a>
- </p>
- <p>
- <a href="https://github.com/oaslananka/kicad-mcp-pro/actions/workflows/ci.yml"><img src="https://github.com/oaslananka/kicad-mcp-pro/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
- <a href="https://github.com/oaslananka/kicad-mcp-pro/actions/workflows/codeql.yml"><img src="https://github.com/oaslananka/kicad-mcp-pro/actions/workflows/codeql.yml/badge.svg?branch=main" alt="CodeQL" /></a>
- <a href="https://securityscorecards.dev/viewer/?uri=github.com/oaslananka/kicad-mcp-pro"><img src="https://api.scorecard.dev/projects/github.com/oaslananka/kicad-mcp-pro/badge" alt="OpenSSF Scorecard" /></a>
- <a href="https://www.bestpractices.dev/projects/12686"><img src="https://www.bestpractices.dev/projects/12686/badge" alt="OpenSSF Best Practices: Passing" /></a>
- </p>
- <!-- parity-coverage-badge:start -->
- [](docs/compatibility/capability-parity.generated.md)
- <!-- parity-coverage-badge:end -->
- <p align="center">
- <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0--only-blue" alt="AGPL-3.0-only license" /></a>
- <a href="https://pepy.tech/projects/kicad-mcp-pro"><img src="https://img.shields.io/pepy/dt/kicad-mcp-pro?label=PyPI%20total" alt="PyPI total downloads" /></a>
- <a href="https://www.npmjs.com/package/kicad-mcp-pro"><img src="https://img.shields.io/npm/dt/kicad-mcp-pro?label=npm%20total" alt="npm total downloads" /></a>
- <a href="https://gitgem.org/github/oaslananka/kicad-mcp-pro"><img src="https://gitgem.org/api/badge/github/oaslananka/kicad-mcp-pro.svg" alt="GitGem" /></a>
- </p>
- <p align="center">
- <a href="https://github.com/sponsors/oaslananka"><img src="https://img.shields.io/badge/GitHub-Sponsors-ea4aaa?logo=githubsponsors" alt="GitHub Sponsors" /></a>
- <a href="https://www.buymeacoffee.com/oaslananka"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Support-ffdd00?logo=buymeacoffee&logoColor=black" alt="Buy Me a Coffee" /></a>
- <a href="https://github.com/oaslananka/kicad-mcp-pro"><img src="https://img.shields.io/github/stars/oaslananka/kicad-mcp-pro?label=Stars&color=8e65d3" alt="Stars" /></a>
- </p>
- </div>
- <!-- mcp-name: io.github.oaslananka/kicad-mcp-pro -->
- KiCad 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.
- The server now starts with the bounded `default` profile: 25 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).
- Telemetry and error reporting are disabled by default. Opt-in OpenTelemetry
- configuration is documented in
- [`docs/configuration.md`](docs/configuration.md#opentelemetry), and privacy rules
- are documented in [`docs/privacy.md`](docs/privacy.md).
- ## Scope and honesty
- KiCad MCP Pro is a **professional first-pass design and review assistant**, not an
- automated sign-off authority. ERC/DRC and the export pipeline drive KiCad's own
- engines. The signal-integrity, power-integrity, EMC, and thermal tools are
- **first-order, closed-form estimates** (typically ~5–10% accuracy) — fast first-pass
- review, **not** a substitute for a 2D/3D field solver, EM/FEA simulation, or formal
- sign-off. Live component sourcing uses the JLCPCB public catalog by default; Nexar,
- DigiKey, and Mouser are available only when their API credentials are configured. What
- fraction of KiCad's programmatic surface the server drives is tracked openly in the
- [capability-parity matrix](docs/compatibility/capability-parity.generated.md). Raw tool count and
- capability coverage are inventory metrics, not the headline product-quality measure. End-to-end
- task outcome, mutation recovery, corruption, required DRC execution, and manufacturing
- reproducibility are the outcome KPIs. The committed
- [native-live example evidence](docs/evidence/task-outcomes/2026-08-28-native-live-example/)
- intentionally reports `insufficient_evidence`; representative-corpus target attainment remains
- separate until the qualification work in #730 is complete.
- ## Project identity
- | Field | Value |
- | --- | --- |
- | Canonical repository | [`oaslananka/kicad-mcp-pro`](https://github.com/oaslananka/kicad-mcp-pro) |
- | PyPI package | [`kicad-mcp-pro`](https://pypi.org/project/kicad-mcp-pro/) |
- | npm wrapper | [`kicad-mcp-pro`](https://www.npmjs.com/package/kicad-mcp-pro) |
- | MCP Registry name | `io.github.oaslananka/kicad-mcp-pro` |
- | Version | `4.19.0` | <!-- x-release-please-version -->
- | OSS maturity report | [`docs/repo-maturity-report.md`](docs/repo-maturity-report.md) |
- | OpenSSF evidence | [`docs/openssf-evidence.md`](docs/openssf-evidence.md) |
- ## Quick Start
- ### Local HTTP and browser dashboard
- No desktop installer or Tauri application is required. The Python server retains
- Streamable HTTP and the browser dashboard. Start the local MCP endpoint:
- ```bash
- uvx kicad-mcp-pro --transport streamable-http --host 127.0.0.1 --port 3334
- ```
- Then connect your MCP client to `http://127.0.0.1:3334/mcp`.
- To open the owner-only browser dashboard:
- ```bash
- uvx kicad-mcp-pro dashboard --host 127.0.0.1 --port 3334 --open
- ```
- The local server and dashboard work without Cloud sign-in. Cloud access is
- optional and requires separate authorization for devices and project metadata.
- See [Installation](docs/installation.md) for setup and security details.
- ### CLI (recommended)
- Install the CLI once with [uv](https://docs.astral.sh/uv/concepts/tools/), then
- use the same command on Windows PowerShell, macOS, or Linux:
- ```bash
- uv tool install kicad-mcp-pro
- kicad-mcp-pro --version
- kicad-mcp-pro setup
- kicad-mcp-pro doctor
- ```
- ### Optional Cloud remote — Windows
- With KiCad MCP Pro installed, open PowerShell and run:
- ```powershell
- kicad-mcp-pro cloud connect
- ```
- On first use, choose a local KiCad project and approve the device pairing
- in your browser. Subsequent starts reuse the paired device and project.
- The terminal stays open and reports **Connected** only after the Cloud
- acknowledges the signed session. Connection events, folder selection and device-bound
- tool calls stream with timestamps and measured durations. Press Ctrl+C to disconnect.
- Foreground mode stops a verified user-owned background Connector task, avoiding
- the extra empty Python console window. On the Cloud Devices page, Add project opens
- the native Windows folder picker; only opaque folder tokens leave your computer.
- Local KiCad files and absolute project paths remain on-device.
- Open the [Cloud Devices page](https://kicad-mcp-pro.oaslananka.dev/devices)
- and choose **Manage access** for the project to grant/revoke each AI client's
- **project-summary** permission. Cloud remote editing is not yet available:
- no write controls are presented as functional. Local MCP use does not require
- a Cloud account. Selecting a different project on a paired device is not yet
- supported in this foreground CLI.
- **Owner-operated Cloud editing (opt-in, not available on the public Cloud by default):**
- After a Cloud operator has enabled the signed write service, obtain its
- **public** Ed25519 issuer key and independently verify the operator-provided
- SHA-256 SPKI fingerprint. From an interactive Windows terminal, for a device
- that is already paired, run:
- ```powershell
- kicad-mcp-pro cloud trust-write-issuer --public-key-file .\issuer-public.pem --sha256 <verified-64-character-SPKI-sha256>
- kicad-mcp-pro cloud connect --enable-native-write
- ```
- The key and fingerprint are pinned to the current Windows user's credential
- store; a different issuer cannot replace them silently. The foreground
- owner command also checks and prepares the Windows-local replay-protection
- directory. Neither command gives an AI app access to any design. The AI client must separately request and
- receive OAuth projects:write consent, then the owner must allow editing for
- that **specific client and project** in Cloud Devices. Existing clients
- and projects remain read-only. The write service and real KiCad save/reopen
- acceptance must be operational before presenting editing as available. Do not
- enable editing on production designs to validate the feature; use a disposable
- KiCad test board and verify its independent on-disk state.
- `setup` guides the local MCP client configuration without requiring a Cloud
- account. For scripts, use `kicad-mcp-pro setup --agent claude-code`; the
- existing `init` and `quickstart` aliases remain supported.
- To check for a stable update or safely remove a CLI installation:
- ```bash
- kicad-mcp-pro update check
- kicad-mcp-pro uninstall
- # If installed with uv, perform the suggested action in your terminal:
- uv tool upgrade kicad-mcp-pro
- uv tool uninstall kicad-mcp-pro
- ```
- `update check` and `uninstall` provide package-manager-aware guidance; they do
- not replace an in-use Python environment or delete KiCad projects. On systems
- with an old pip and a newer uv executable in `PATH`, run `doctor` before
- uninstalling anything. See [CLI installation and version management](docs/installation.md#terminal-cli-recommended)
- for the full instructions. Optional Cloud requires separate browser pairing
- and owner approval; local MCP does not depend on it.
- For disposable testing without a persistent installation, `uvx kicad-mcp-pro
- quickstart` remains available. Use `dashboard --open` for the local browser UI,
- or `--transport streamable-http --port 3334` to run an HTTP MCP endpoint.
- ### KiCad PCB Editor Companion (development preview)
- The existing KiCad PCM Companion is being upgraded to a KiCad 10 IPC toolbar
- plugin in [packages/kicad-plugin/](packages/kicad-plugin/). It reads the active
- PCB and links to the existing local dashboard. The IPC upgrade is read-only;
- live desktop acceptance and release are pending.
- ### Web Dashboard
- ```bash
- uvx kicad-mcp-pro dashboard --host 127.0.0.1 --port 3334 --open
- # http://127.0.0.1:3334/ui
- ```
- ## Documentation
- The documentation is organized from setup to operation:
- 1. [Installation](docs/installation.md)
- 2. [Client configuration](docs/client-configuration.md)
- 3. [Runtime configuration](docs/configuration.md)
- 4. [Tool reference](docs/tools-reference.md)
- 5. [Workflows](docs/workflows/first-pcb.md)
- 6. [Release process](docs/release-process.md)
- 7. [Security and privacy](docs/security/threat-model.md)
- 8. [KiCad capability parity](docs/compatibility/capability-parity.generated.md) — how much of KiCad's programmatic surface this server drives
- 9. [Error code catalog](docs/errors.md) — stable error codes, retry classes, and recovery
- 10. [Work-order audit](docs/status/work-order-audit-2026-06-17.md) — current status of the hardening work order
- The `kicad_capability_parity()` tool reports, per workflow domain, what fraction of
- KiCad's programmatically reachable surface this server can drive (currently **76.6%**),
- keeping genuine `gap`s distinct from `gui-only-no-api` items that KiCad exposes no
- headless API for.
- The published documentation site is available at
- [https://oaslananka.github.io/kicad-mcp-pro/](https://oaslananka.github.io/kicad-mcp-pro/).
- ## Transports
- KiCad MCP Pro supports `stdio` and Streamable HTTP. Streamable HTTP is served at
- `/mcp` by default and can be moved with `KICAD_MCP_MOUNT_PATH`.
- ```bash
- uvx kicad-mcp-pro --transport streamable-http --host 127.0.0.1 --port 3334
- ```
- Streamable HTTP clients must send `Accept: application/json, text/event-stream` and
- `Content-Type: application/json`. The primary public MCP contract is
- `2026-07-28`: modern clients send `MCP-Protocol-Version: 2026-07-28`, the
- method/name transport headers required by the final protocol, and the per-request
- client metadata envelope.
- Backward-compatible `2025-11-25` clients remain supported through the SDK's
- legacy `initialize` negotiation. Those clients echo the negotiated protocol
- version on follow-up requests and, when `KICAD_MCP_STATEFUL_HTTP=1`, also echo
- `MCP-Session-Id`. Final `2026-07-28` traffic is stateless and does not create MCP
- sessions.
- The deprecated HTTP+SSE fallback routes are disabled by default. Set
- `KICAD_MCP_LEGACY_SSE=1` only for older clients that cannot use Streamable HTTP.
- ## Install
- Published packages:
- ```bash
- uvx kicad-mcp-pro --help
- npx kicad-mcp-pro --help
- ```
- Fresh source checkout on supported Linux hosts:
- ```bash
- ./scripts/bootstrap-dev.sh
- source .dev-env.sh
- pnpm run dev:doctor -- --ci
- ```
- The repository bootstrap installs checksum-pinned Python, uv/uvx, Node.js,
- pnpm, Task, and Rust tooling into ignored checkout-local roots and performs
- frozen dependency installation. It does not modify global tool directories.
- See the [reproducible bootstrap guide](docs/development/reproducible-bootstrap.md)
- for `--core-only`, `--check`, cleanup, upgrade, and KiCad capability modes.
- ## Package metadata
- The 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.
- ## Fast local setup
- Open a terminal in a KiCad project directory and run:
- ```bash
- uvx kicad-mcp-pro quickstart
- ```
- This detects a supported local agent, configures its MCP entry in read-only mode,
- installs bundled skills where supported, backs up existing settings, and verifies
- the saved launch command over stdio. Cloud login
- is optional and is not required for local use. See the [installation guide](docs/agents/install.md)
- for details and explicit agent selection.
- ## Usage
- Use `kicad-mcp-pro --help` to inspect CLI commands and
- [`docs/client-configuration.md`](docs/client-configuration.md) to configure an
- MCP client. The generated tool catalog is available in
- [`docs/tools-reference.generated.md`](docs/tools-reference.generated.md).
- ## Agent plugin and skills
- This repository owns the product-level agent plugin and KiCad-specific skills for
- KiCad MCP Pro. The central [`agent-tools`](https://github.com/oaslananka/agent-tools)
- repository should catalog this plugin, but the manifest and workflow instructions live
- here so they stay synchronized with the actual MCP server tools.
- | File | Purpose |
- | --- | --- |
- | [`plugin.json`](plugin.json), [`mcp.json`](mcp.json) | Generated portable plugin package with canonical skills and a version-pinned local MCP launcher. |
- | [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json) | Product-level plugin manifest for compatible agent runtimes and marketplace catalogs. |
- | [`.mcp.json`](.mcp.json) | Claude Code project-local MCP server configuration. |
- | [`.codex/config.example.toml`](.codex/config.example.toml) | Codex CLI MCP configuration example. |
- | [`.vscode/mcp.example.json`](.vscode/mcp.example.json) | VS Code / GitHub Copilot workspace MCP configuration example. |
- | [`integrations/opencode/opencode.example.json`](integrations/opencode/opencode.example.json) | OpenCode project MCP configuration example. |
- | [`.opencode/skills/`](.opencode/skills) | OpenCode-native mirrored skill definitions. |
- | [`docs/agent-runtime-config.md`](docs/agent-runtime-config.md) | Agent runtime setup and validation matrix. |
- | [`skills/kicad-design-review/SKILL.md`](skills/kicad-design-review/SKILL.md) | Comprehensive KiCad design review skill. |
- | [`skills/pcb-design/SKILL.md`](skills/pcb-design/SKILL.md) | PCB design, layout inspection, placement, routing, stackup, and board-quality workflow. |
- | [`skills/drc-check/SKILL.md`](skills/drc-check/SKILL.md) | ERC/DRC execution, triage, waiver review, and revalidation workflow. |
- | [`skills/fabrication-output/SKILL.md`](skills/fabrication-output/SKILL.md) | Manufacturing export, DFM, release evidence, and fabrication-package workflow. |
- | [`skills/schematic-review/SKILL.md`](skills/schematic-review/SKILL.md) | Schematic inspection, ERC, connectivity, power, symbol, and readability workflow. |
- ### Agent setup
- KiCad MCP Pro can be launched with the published Python package, npm wrapper, or the
- container metadata declared in [`server.json`](server.json). Common local starts are:
- ```bash
- uvx kicad-mcp-pro --transport stdio
- uvx kicad-mcp-pro --transport streamable-http --host 127.0.0.1 --port 3334
- npx kicad-mcp-pro --help
- ```
- For source checkouts, run the normal repository validation path before publishing plugin
- changes:
- ```bash
- pnpm run metadata:check
- python3 -m json.tool .claude-plugin/plugin.json >/dev/null
- ```
- ### Validation workflow
- Before listing this plugin as active from `agent-tools`, verify at least one compatible
- agent runtime can:
- 1. Discover `.claude-plugin/plugin.json`.
- 2. Launch or connect to `kicad-mcp-pro` over `stdio` or Streamable HTTP.
- 3. Call `kicad_get_server_info` or `kicad_get_project_info`.
- 4. Load a skill from `skills/` and follow the workflow without referencing missing tools.
- 5. Report ERC, DRC, DFM, export artifacts, assumptions, and human-review requirements
- separately.
- KiCad MCP Pro is an engineering assistant, not an autonomous manufacturing sign-off
- authority. Generated PCB and fabrication outputs require qualified human review before
- fabrication or assembly.
- ## Development
- New contributors should start with [`ARCHITECTURE.md`](ARCHITECTURE.md), which maps
- the five layers (transport → MCP protocol → orchestration → KiCad adapter seam →
- pure domain) and shows exactly how to add a new tool. The runtime model and
- quality-gate stack are documented in
- [`docs/development/architecture.md`](docs/development/architecture.md).
- The project uses a `Taskfile.yml` for common development commands. After
- cloning the repository:
- ```bash
- task install # Install all dependencies (pnpm + uv)
- task verify # Run the local quality gate: lint → format → typecheck → test → build
- task test # Run unit tests only
- task lint # Run lint and metadata checks
- task format # Auto-format the codebase
- task typecheck # Run strict static type checking
- task build # Build release artifacts
- task ci # Run the local equivalent of the full CI pipeline
- task hooks # Install repository-pinned Lefthook git hooks
- ```
- All changes must pass `task verify` before opening a pull request.
- ## Contributing
- Read [`CONTRIBUTING.md`](CONTRIBUTING.md) before opening a pull request. All
- changes must pass the repository's format, lint, type-check, test, workflow,
- security, and package metadata gates.
- ## Independent industry coverage
- - **JLCPCB (October 14, 2026)** — [KiCad MCP: How to Design a PCB with Claude Code](https://jlcpcb.com/blog/kicad-mcp-how-to-design-a-pcb-with-claude-code) documents a hands-on KiCad MCP Pro workflow for an XL4015/LM358 buck-converter design, including checks and limitations. The board was not fabricated or bench-tested. This is independent coverage, not a JLCPCB endorsement or partnership; reported issues are being evaluated in [#1314](https://github.com/oaslananka/kicad-mcp-pro/issues/1314).
- ## Cite this software
- If you use KiCad MCP Pro in research or a technical publication, cite the
- archived release via its DOI (see [`CITATION.cff`](CITATION.cff) for full
- metadata):
- ```bibtex
- @software{aslan_kicad_mcp_pro,
- author = {Aslan, Osman},
- title = {KiCad MCP Pro},
- license = {AGPL-3.0-only},
- url = {https://github.com/oaslananka/kicad-mcp-pro},
- doi = {10.5281/zenodo.21283791}
- }
- ```
- Every GitHub release is archived on Zenodo under this concept DOI, which
- always resolves to the most recent version.
- ## License
- KiCad MCP Pro project-authored source is licensed under [GNU AGPL v3.0](LICENSE).
apps/cloud/scripts/offsite-restore-verify.sh · Bundled script · 83 lines · 1 finding marked
- #!/usr/bin/env bash
- # Run on a SECOND, operator-controlled machine containing only the encrypted
- # archive. Identity is injected from the external secret manager on that host.
- # No production connection, Docker network, plaintext dump or host volume.
- set -euo pipefail
- umask 077
- if [[ $# -ne 1 ]]; then
- echo 'Usage: EXPECTED_SHA256=<digest> EXPECTED_SCHEMA_VERSION=<reviewed-version> doppler run -p kicad-mcp-pro -c prd_cloud -- bash scripts/offsite-restore-verify.sh /private/backup.pg.age' >&2
- exit 2
- fi
- archive="$1"
- [[ -f "$archive" && -s "$archive" && ! -L "$archive" ]] || {
- echo 'Encrypted offsite archive is missing, empty or linked' >&2; exit 2;
- }
- [[ ! -L "$(dirname "$archive")" ]] || { echo 'Refusing linked archive directory' >&2; exit 2; }
- mode=$(stat -c '%a' "$archive")
- (( (8#$mode & 077) == 0 )) || { echo 'Offsite archive is readable by others' >&2; exit 2; }
- [[ "${EXPECTED_SHA256:-}" =~ ^[a-f0-9]{64}$ ]] || { echo 'Expected encrypted archive SHA-256 required' >&2; exit 2; }
- [[ "$(sha256sum "$archive" | awk '{print $1}')" == "$EXPECTED_SHA256" ]] || {
- echo 'Encrypted offsite archive differs from source receipt' >&2; exit 1;
- }
- [[ "${EXPECTED_SCHEMA_VERSION:-}" =~ ^[1-9][0-9]{0,2}$ ]] || {
- echo 'Expected positive reviewed schema version required' >&2; exit 2;
- }
- [[ "${EXPECTED_LEDGER:-}" =~ ^[1-9][0-9]*:[a-f0-9]{32}$ &&
- "${EXPECTED_LEDGER%%:*}" == "$EXPECTED_SCHEMA_VERSION" ]] || {
- echo 'Source migration checksum receipt/count must match schema version' >&2; exit 2;
- }
- [[ -n "${KICAD_BACKUP_AGE_IDENTITY:-}" && -n "${KICAD_BACKUP_AGE_RECIPIENT:-}" ]] || {
- echo 'Independent operator must provide authorized age identity through secret manager' >&2; exit 2;
- }
- for cmd in docker age age-keygen openssl mktemp; do command -v "$cmd" >/dev/null || { echo "Missing restore tool: $cmd" >&2; exit 2; }; done
- [[ -d /dev/shm ]] || { echo 'RAM-only key staging unavailable' >&2; exit 2; }
- tmp=$(mktemp -d /dev/shm/kicad-offsite-recovery.XXXXXXXX)
- target="kicad-offsite-restore-$(openssl rand -hex 6)"
- cleanup(){ docker rm -f "$target" >/dev/null 2>&1 || true; rm -rf -- "$tmp"; }
- trap cleanup EXIT
- printf '%s\n' "$KICAD_BACKUP_AGE_IDENTITY" > "$tmp/identity"
- chmod 600 "$tmp/identity"
- [[ "$(age-keygen -y "$tmp/identity")" == "$KICAD_BACKUP_AGE_RECIPIENT" ]] || {
- echo 'Independent recovery identity/recipient mismatch' >&2; exit 1;
- }
- password=$(openssl rand -hex 24)
- docker run --rm -d --network none --name "$target" \
- --tmpfs /var/lib/postgresql/data:rw,size=256m \
- --tmpfs /var/run/postgresql:rw,size=16m \
- --tmpfs /tmp:rw,size=16m \
- -e POSTGRES_USER=offsite_fixture -e POSTGRES_DB=offsite_fixture \
- -e "POSTGRES_PASSWORD=$password" postgres:17-alpine >/dev/null
- # Docker represents --tmpfs in HostConfig.Tmpfs rather than .Mounts.
- [[ $(docker inspect "$target" --format '{{index .HostConfig.Tmpfs "/var/lib/postgresql/data"}}') == *size=256m* ]] || {
- echo 'Temporary database is not RAM-backed; refusing decryption' >&2; exit 1;
- }
- ready=false
- for _ in $(seq 1 45); do
- # pg_isready alone is insufficient: the image bootstraps a temporary PG
- # server, shuts it down and starts the actual server.
- if docker logs "$target" 2>&1 | grep -q 'PostgreSQL init process complete; ready for start up' && \
- docker exec "$target" pg_isready -q -U offsite_fixture -d offsite_fixture; then
- ready=true; break
- fi
- sleep 1
- done
- [[ "$ready" == true ]] || { echo 'PostgreSQL final boot was not confirmed' >&2; exit 1; }
- # No plaintext archive or password is written to any durable volume.
- Note: Quoted as data in code: Asks you to extract a password-protected archive, the usual way malware droppers get past scanners
- Line 65 on GitHub
- age -d -i "$tmp/identity" "$archive" |
- docker exec -i "$target" pg_restore --exit-on-error --no-owner --no-acl \
- -U offsite_fixture -d offsite_fixture >/dev/null
- query(){ docker exec "$target" psql -X -A -t -q -v ON_ERROR_STOP=1 \
- -U offsite_fixture -d offsite_fixture -c "$1"; }
- version=$(query 'SELECT max(version) FROM schema_migrations')
- [[ "$version" == "$EXPECTED_SCHEMA_VERSION" ]] || { echo 'Recovered schema version differs' >&2; exit 1; }
- ledger=$(query "SELECT count(*)::text || ':' || coalesce(md5(string_agg(version::text || ':' || checksum, '|' ORDER BY version)), '') FROM schema_migrations")
- if [[ "$ledger" != "$EXPECTED_LEDGER" ]]; then
- echo 'Recovered migration checksums differ from signed-off source receipt' >&2; exit 1
- fi
- triggers=$(query "SELECT count(*) FROM pg_trigger WHERE NOT tgisinternal AND tgname IN ('kicad_fence_refresh_insert','kicad_fence_opaque_access_insert','kicad_fence_refresh_replay')")
- [[ "$triggers" == 3 ]] || { echo 'OAuth security fences absent from restore' >&2; exit 1; }
- for table in devices projects project_client_grants '"users"' '"oauthClient"' '"oauthConsent"'; do
- count=$(query "SELECT count(*) FROM $table")
- [[ "$count" =~ ^[0-9]+$ ]] || { echo 'Metadata table unreadable after restore' >&2; exit 1; }
- done
- printf 'PASS: offsite encrypted restore, RAM-only isolated PG17, schema %s, ledger %s, OAuth fences %s\n' "$version" "$ledger" "$triggers"
Version history
v4.19.011/18/2026
v4.17.011/17/2026
v4.16.011/15/2026
v4.14.011/13/2026
v4.12.011/11/2026
v4.10.011/9/2026
v4.9.011/8/2026
v4.8.111/7/2026
v4.7.011/5/2026
v4.6.111/1/2026
v4.5.010/31/2026
v4.4.010/24/2026
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.