Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/oaslananka--kicad-mcp-pro/badge.svg)](/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

i

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
  1. {
  2. "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
  3. "name": "kicad-pro",
  4. "version": "4.19.0",
  5. "description": "KiCad MCP Pro plugin for schematic review, PCB design assistance, DRC/ERC validation, DFM checks, and manufacturing release workflows.",
  6. "mcpServers": "./.mcp.json",
  7. "skills": [
  8. "./skills/kicad-design-review",
  9. "./skills/pcb-design",
  10. "./skills/drc-check",
  11. "./skills/fabrication-output",
  12. "./skills/schematic-review",
  13. "./skills/visual-excellence",
  14. "./skills/wired-subcircuit-design"
  15. ],
  16. "author": {
  17. "name": "oaslananka",
  18. "url": "https://github.com/oaslananka"
  19. }
  20. }
README.md · README · 423 lines
  1. <div align="center">
  2. <h1>KiCad MCP Pro</h1>
  3. <p>
  4. <strong>Drive KiCad schematic, PCB, DRC/ERC, DFM, and manufacturing review from any MCP-capable AI agent.</strong>
  5. </p>
  6. <p>
  7. <a href="https://oaslananka.github.io/kicad-mcp-pro/">Documentation</a> ·
  8. <a href="docs/installation.md">Installation</a> ·
  9. <a href="#quick-start">Quick Start</a> ·
  10. <a href="docs/tools-reference.generated.md">Tool Reference</a> ·
  11. <a href="https://oaslananka.github.io/kicad-mcp-pro/agents/">AI Agent Setup</a> ·
  12. <a href="docs/llms.txt">AI discovery</a> ·
  13. <a href="https://deepwiki.com/oaslananka/kicad-mcp-pro">Ask DeepWiki</a>
  14. </p>
  15. <p>
  16. <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>
  17. <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>
  18. <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>
  19. <a href="https://doi.org/10.5281/zenodo.21283791"><img src="https://zenodo.org/badge/1255527274.svg" alt="DOI" /></a>
  20. </p>
  21. <p>
  22. <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>
  23. <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>
  24. <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>
  25. <a href="https://www.bestpractices.dev/projects/12686"><img src="https://www.bestpractices.dev/projects/12686/badge" alt="OpenSSF Best Practices: Passing" /></a>
  26. </p>
  27. <!-- parity-coverage-badge:start -->
  28. [![KiCad programmatic parity](https://img.shields.io/badge/KiCad_programmatic_parity-84.4%25-green)](docs/compatibility/capability-parity.generated.md)
  29. <!-- parity-coverage-badge:end -->
  30. <p align="center">
  31. <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0--only-blue" alt="AGPL-3.0-only license" /></a>
  32. <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>
  33. <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>
  34. <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>
  35. </p>
  36. <p align="center">
  37. <a href="https://github.com/sponsors/oaslananka"><img src="https://img.shields.io/badge/GitHub-Sponsors-ea4aaa?logo=githubsponsors" alt="GitHub Sponsors" /></a>
  38. <a href="https://www.buymeacoffee.com/oaslananka"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Support-ffdd00?logo=buymeacoffee&amp;logoColor=black" alt="Buy Me a Coffee" /></a>
  39. <a href="https://github.com/oaslananka/kicad-mcp-pro"><img src="https://img.shields.io/github/stars/oaslananka/kicad-mcp-pro?label=Stars&amp;color=8e65d3" alt="Stars" /></a>
  40. </p>
  41. </div>
  42. <!-- mcp-name: io.github.oaslananka/kicad-mcp-pro -->
  43. 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.
  44. 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).
  45. Telemetry and error reporting are disabled by default. Opt-in OpenTelemetry
  46. configuration is documented in
  47. [`docs/configuration.md`](docs/configuration.md#opentelemetry), and privacy rules
  48. are documented in [`docs/privacy.md`](docs/privacy.md).
  49. ## Scope and honesty
  50. KiCad MCP Pro is a **professional first-pass design and review assistant**, not an
  51. automated sign-off authority. ERC/DRC and the export pipeline drive KiCad's own
  52. engines. The signal-integrity, power-integrity, EMC, and thermal tools are
  53. **first-order, closed-form estimates** (typically ~5–10% accuracy) — fast first-pass
  54. review, **not** a substitute for a 2D/3D field solver, EM/FEA simulation, or formal
  55. sign-off. Live component sourcing uses the JLCPCB public catalog by default; Nexar,
  56. DigiKey, and Mouser are available only when their API credentials are configured. What
  57. fraction of KiCad's programmatic surface the server drives is tracked openly in the
  58. [capability-parity matrix](docs/compatibility/capability-parity.generated.md). Raw tool count and
  59. capability coverage are inventory metrics, not the headline product-quality measure. End-to-end
  60. task outcome, mutation recovery, corruption, required DRC execution, and manufacturing
  61. reproducibility are the outcome KPIs. The committed
  62. [native-live example evidence](docs/evidence/task-outcomes/2026-08-28-native-live-example/)
  63. intentionally reports `insufficient_evidence`; representative-corpus target attainment remains
  64. separate until the qualification work in #730 is complete.
  65. ## Project identity
  66. | Field | Value |
  67. | --- | --- |
  68. | Canonical repository | [`oaslananka/kicad-mcp-pro`](https://github.com/oaslananka/kicad-mcp-pro) |
  69. | PyPI package | [`kicad-mcp-pro`](https://pypi.org/project/kicad-mcp-pro/) |
  70. | npm wrapper | [`kicad-mcp-pro`](https://www.npmjs.com/package/kicad-mcp-pro) |
  71. | MCP Registry name | `io.github.oaslananka/kicad-mcp-pro` |
  72. | Version | `4.19.0` | <!-- x-release-please-version -->
  73. | OSS maturity report | [`docs/repo-maturity-report.md`](docs/repo-maturity-report.md) |
  74. | OpenSSF evidence | [`docs/openssf-evidence.md`](docs/openssf-evidence.md) |
  75. ## Quick Start
  76. ### Local HTTP and browser dashboard
  77. No desktop installer or Tauri application is required. The Python server retains
  78. Streamable HTTP and the browser dashboard. Start the local MCP endpoint:
  79. ```bash
  80. uvx kicad-mcp-pro --transport streamable-http --host 127.0.0.1 --port 3334
  81. ```
  82. Then connect your MCP client to `http://127.0.0.1:3334/mcp`.
  83. To open the owner-only browser dashboard:
  84. ```bash
  85. uvx kicad-mcp-pro dashboard --host 127.0.0.1 --port 3334 --open
  86. ```
  87. The local server and dashboard work without Cloud sign-in. Cloud access is
  88. optional and requires separate authorization for devices and project metadata.
  89. See [Installation](docs/installation.md) for setup and security details.
  90. ### CLI (recommended)
  91. Install the CLI once with [uv](https://docs.astral.sh/uv/concepts/tools/), then
  92. use the same command on Windows PowerShell, macOS, or Linux:
  93. ```bash
  94. uv tool install kicad-mcp-pro
  95. kicad-mcp-pro --version
  96. kicad-mcp-pro setup
  97. kicad-mcp-pro doctor
  98. ```
  99. ### Optional Cloud remote — Windows
  100. With KiCad MCP Pro installed, open PowerShell and run:
  101. ```powershell
  102. kicad-mcp-pro cloud connect
  103. ```
  104. On first use, choose a local KiCad project and approve the device pairing
  105. in your browser. Subsequent starts reuse the paired device and project.
  106. The terminal stays open and reports **Connected** only after the Cloud
  107. acknowledges the signed session. Connection events, folder selection and device-bound
  108. tool calls stream with timestamps and measured durations. Press Ctrl+C to disconnect.
  109. Foreground mode stops a verified user-owned background Connector task, avoiding
  110. the extra empty Python console window. On the Cloud Devices page, Add project opens
  111. the native Windows folder picker; only opaque folder tokens leave your computer.
  112. Local KiCad files and absolute project paths remain on-device.
  113. Open the [Cloud Devices page](https://kicad-mcp-pro.oaslananka.dev/devices)
  114. and choose **Manage access** for the project to grant/revoke each AI client's
  115. **project-summary** permission. Cloud remote editing is not yet available:
  116. no write controls are presented as functional. Local MCP use does not require
  117. a Cloud account. Selecting a different project on a paired device is not yet
  118. supported in this foreground CLI.
  119. **Owner-operated Cloud editing (opt-in, not available on the public Cloud by default):**
  120. After a Cloud operator has enabled the signed write service, obtain its
  121. **public** Ed25519 issuer key and independently verify the operator-provided
  122. SHA-256 SPKI fingerprint. From an interactive Windows terminal, for a device
  123. that is already paired, run:
  124. ```powershell
  125. kicad-mcp-pro cloud trust-write-issuer --public-key-file .\issuer-public.pem --sha256 <verified-64-character-SPKI-sha256>
  126. kicad-mcp-pro cloud connect --enable-native-write
  127. ```
  128. The key and fingerprint are pinned to the current Windows user's credential
  129. store; a different issuer cannot replace them silently. The foreground
  130. owner command also checks and prepares the Windows-local replay-protection
  131. directory. Neither command gives an AI app access to any design. The AI client must separately request and
  132. receive OAuth projects:write consent, then the owner must allow editing for
  133. that **specific client and project** in Cloud Devices. Existing clients
  134. and projects remain read-only. The write service and real KiCad save/reopen
  135. acceptance must be operational before presenting editing as available. Do not
  136. enable editing on production designs to validate the feature; use a disposable
  137. KiCad test board and verify its independent on-disk state.
  138. `setup` guides the local MCP client configuration without requiring a Cloud
  139. account. For scripts, use `kicad-mcp-pro setup --agent claude-code`; the
  140. existing `init` and `quickstart` aliases remain supported.
  141. To check for a stable update or safely remove a CLI installation:
  142. ```bash
  143. kicad-mcp-pro update check
  144. kicad-mcp-pro uninstall
  145. # If installed with uv, perform the suggested action in your terminal:
  146. uv tool upgrade kicad-mcp-pro
  147. uv tool uninstall kicad-mcp-pro
  148. ```
  149. `update check` and `uninstall` provide package-manager-aware guidance; they do
  150. not replace an in-use Python environment or delete KiCad projects. On systems
  151. with an old pip and a newer uv executable in `PATH`, run `doctor` before
  152. uninstalling anything. See [CLI installation and version management](docs/installation.md#terminal-cli-recommended)
  153. for the full instructions. Optional Cloud requires separate browser pairing
  154. and owner approval; local MCP does not depend on it.
  155. For disposable testing without a persistent installation, `uvx kicad-mcp-pro
  156. quickstart` remains available. Use `dashboard --open` for the local browser UI,
  157. or `--transport streamable-http --port 3334` to run an HTTP MCP endpoint.
  158. ### KiCad PCB Editor Companion (development preview)
  159. The existing KiCad PCM Companion is being upgraded to a KiCad 10 IPC toolbar
  160. plugin in [packages/kicad-plugin/](packages/kicad-plugin/). It reads the active
  161. PCB and links to the existing local dashboard. The IPC upgrade is read-only;
  162. live desktop acceptance and release are pending.
  163. ### Web Dashboard
  164. ```bash
  165. uvx kicad-mcp-pro dashboard --host 127.0.0.1 --port 3334 --open
  166. # http://127.0.0.1:3334/ui
  167. ```
  168. ## Documentation
  169. The documentation is organized from setup to operation:
  170. 1. [Installation](docs/installation.md)
  171. 2. [Client configuration](docs/client-configuration.md)
  172. 3. [Runtime configuration](docs/configuration.md)
  173. 4. [Tool reference](docs/tools-reference.md)
  174. 5. [Workflows](docs/workflows/first-pcb.md)
  175. 6. [Release process](docs/release-process.md)
  176. 7. [Security and privacy](docs/security/threat-model.md)
  177. 8. [KiCad capability parity](docs/compatibility/capability-parity.generated.md) — how much of KiCad's programmatic surface this server drives
  178. 9. [Error code catalog](docs/errors.md) — stable error codes, retry classes, and recovery
  179. 10. [Work-order audit](docs/status/work-order-audit-2026-06-17.md) — current status of the hardening work order
  180. The `kicad_capability_parity()` tool reports, per workflow domain, what fraction of
  181. KiCad's programmatically reachable surface this server can drive (currently **76.6%**),
  182. keeping genuine `gap`s distinct from `gui-only-no-api` items that KiCad exposes no
  183. headless API for.
  184. The published documentation site is available at
  185. [https://oaslananka.github.io/kicad-mcp-pro/](https://oaslananka.github.io/kicad-mcp-pro/).
  186. ## Transports
  187. KiCad MCP Pro supports `stdio` and Streamable HTTP. Streamable HTTP is served at
  188. `/mcp` by default and can be moved with `KICAD_MCP_MOUNT_PATH`.
  189. ```bash
  190. uvx kicad-mcp-pro --transport streamable-http --host 127.0.0.1 --port 3334
  191. ```
  192. Streamable HTTP clients must send `Accept: application/json, text/event-stream` and
  193. `Content-Type: application/json`. The primary public MCP contract is
  194. `2026-07-28`: modern clients send `MCP-Protocol-Version: 2026-07-28`, the
  195. method/name transport headers required by the final protocol, and the per-request
  196. client metadata envelope.
  197. Backward-compatible `2025-11-25` clients remain supported through the SDK's
  198. legacy `initialize` negotiation. Those clients echo the negotiated protocol
  199. version on follow-up requests and, when `KICAD_MCP_STATEFUL_HTTP=1`, also echo
  200. `MCP-Session-Id`. Final `2026-07-28` traffic is stateless and does not create MCP
  201. sessions.
  202. The deprecated HTTP+SSE fallback routes are disabled by default. Set
  203. `KICAD_MCP_LEGACY_SSE=1` only for older clients that cannot use Streamable HTTP.
  204. ## Install
  205. Published packages:
  206. ```bash
  207. uvx kicad-mcp-pro --help
  208. npx kicad-mcp-pro --help
  209. ```
  210. Fresh source checkout on supported Linux hosts:
  211. ```bash
  212. ./scripts/bootstrap-dev.sh
  213. source .dev-env.sh
  214. pnpm run dev:doctor -- --ci
  215. ```
  216. The repository bootstrap installs checksum-pinned Python, uv/uvx, Node.js,
  217. pnpm, Task, and Rust tooling into ignored checkout-local roots and performs
  218. frozen dependency installation. It does not modify global tool directories.
  219. See the [reproducible bootstrap guide](docs/development/reproducible-bootstrap.md)
  220. for `--core-only`, `--check`, cleanup, upgrade, and KiCad capability modes.
  221. ## Package metadata
  222. 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.
  223. ## Fast local setup
  224. Open a terminal in a KiCad project directory and run:
  225. ```bash
  226. uvx kicad-mcp-pro quickstart
  227. ```
  228. This detects a supported local agent, configures its MCP entry in read-only mode,
  229. installs bundled skills where supported, backs up existing settings, and verifies
  230. the saved launch command over stdio. Cloud login
  231. is optional and is not required for local use. See the [installation guide](docs/agents/install.md)
  232. for details and explicit agent selection.
  233. ## Usage
  234. Use `kicad-mcp-pro --help` to inspect CLI commands and
  235. [`docs/client-configuration.md`](docs/client-configuration.md) to configure an
  236. MCP client. The generated tool catalog is available in
  237. [`docs/tools-reference.generated.md`](docs/tools-reference.generated.md).
  238. ## Agent plugin and skills
  239. This repository owns the product-level agent plugin and KiCad-specific skills for
  240. KiCad MCP Pro. The central [`agent-tools`](https://github.com/oaslananka/agent-tools)
  241. repository should catalog this plugin, but the manifest and workflow instructions live
  242. here so they stay synchronized with the actual MCP server tools.
  243. | File | Purpose |
  244. | --- | --- |
  245. | [`plugin.json`](plugin.json), [`mcp.json`](mcp.json) | Generated portable plugin package with canonical skills and a version-pinned local MCP launcher. |
  246. | [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json) | Product-level plugin manifest for compatible agent runtimes and marketplace catalogs. |
  247. | [`.mcp.json`](.mcp.json) | Claude Code project-local MCP server configuration. |
  248. | [`.codex/config.example.toml`](.codex/config.example.toml) | Codex CLI MCP configuration example. |
  249. | [`.vscode/mcp.example.json`](.vscode/mcp.example.json) | VS Code / GitHub Copilot workspace MCP configuration example. |
  250. | [`integrations/opencode/opencode.example.json`](integrations/opencode/opencode.example.json) | OpenCode project MCP configuration example. |
  251. | [`.opencode/skills/`](.opencode/skills) | OpenCode-native mirrored skill definitions. |
  252. | [`docs/agent-runtime-config.md`](docs/agent-runtime-config.md) | Agent runtime setup and validation matrix. |
  253. | [`skills/kicad-design-review/SKILL.md`](skills/kicad-design-review/SKILL.md) | Comprehensive KiCad design review skill. |
  254. | [`skills/pcb-design/SKILL.md`](skills/pcb-design/SKILL.md) | PCB design, layout inspection, placement, routing, stackup, and board-quality workflow. |
  255. | [`skills/drc-check/SKILL.md`](skills/drc-check/SKILL.md) | ERC/DRC execution, triage, waiver review, and revalidation workflow. |
  256. | [`skills/fabrication-output/SKILL.md`](skills/fabrication-output/SKILL.md) | Manufacturing export, DFM, release evidence, and fabrication-package workflow. |
  257. | [`skills/schematic-review/SKILL.md`](skills/schematic-review/SKILL.md) | Schematic inspection, ERC, connectivity, power, symbol, and readability workflow. |
  258. ### Agent setup
  259. KiCad MCP Pro can be launched with the published Python package, npm wrapper, or the
  260. container metadata declared in [`server.json`](server.json). Common local starts are:
  261. ```bash
  262. uvx kicad-mcp-pro --transport stdio
  263. uvx kicad-mcp-pro --transport streamable-http --host 127.0.0.1 --port 3334
  264. npx kicad-mcp-pro --help
  265. ```
  266. For source checkouts, run the normal repository validation path before publishing plugin
  267. changes:
  268. ```bash
  269. pnpm run metadata:check
  270. python3 -m json.tool .claude-plugin/plugin.json >/dev/null
  271. ```
  272. ### Validation workflow
  273. Before listing this plugin as active from `agent-tools`, verify at least one compatible
  274. agent runtime can:
  275. 1. Discover `.claude-plugin/plugin.json`.
  276. 2. Launch or connect to `kicad-mcp-pro` over `stdio` or Streamable HTTP.
  277. 3. Call `kicad_get_server_info` or `kicad_get_project_info`.
  278. 4. Load a skill from `skills/` and follow the workflow without referencing missing tools.
  279. 5. Report ERC, DRC, DFM, export artifacts, assumptions, and human-review requirements
  280. separately.
  281. KiCad MCP Pro is an engineering assistant, not an autonomous manufacturing sign-off
  282. authority. Generated PCB and fabrication outputs require qualified human review before
  283. fabrication or assembly.
  284. ## Development
  285. New contributors should start with [`ARCHITECTURE.md`](ARCHITECTURE.md), which maps
  286. the five layers (transport → MCP protocol → orchestration → KiCad adapter seam →
  287. pure domain) and shows exactly how to add a new tool. The runtime model and
  288. quality-gate stack are documented in
  289. [`docs/development/architecture.md`](docs/development/architecture.md).
  290. The project uses a `Taskfile.yml` for common development commands. After
  291. cloning the repository:
  292. ```bash
  293. task install # Install all dependencies (pnpm + uv)
  294. task verify # Run the local quality gate: lint → format → typecheck → test → build
  295. task test # Run unit tests only
  296. task lint # Run lint and metadata checks
  297. task format # Auto-format the codebase
  298. task typecheck # Run strict static type checking
  299. task build # Build release artifacts
  300. task ci # Run the local equivalent of the full CI pipeline
  301. task hooks # Install repository-pinned Lefthook git hooks
  302. ```
  303. All changes must pass `task verify` before opening a pull request.
  304. ## Contributing
  305. Read [`CONTRIBUTING.md`](CONTRIBUTING.md) before opening a pull request. All
  306. changes must pass the repository's format, lint, type-check, test, workflow,
  307. security, and package metadata gates.
  308. ## Independent industry coverage
  309. - **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).
  310. ## Cite this software
  311. If you use KiCad MCP Pro in research or a technical publication, cite the
  312. archived release via its DOI (see [`CITATION.cff`](CITATION.cff) for full
  313. metadata):
  314. ```bibtex
  315. @software{aslan_kicad_mcp_pro,
  316. author = {Aslan, Osman},
  317. title = {KiCad MCP Pro},
  318. license = {AGPL-3.0-only},
  319. url = {https://github.com/oaslananka/kicad-mcp-pro},
  320. doi = {10.5281/zenodo.21283791}
  321. }
  322. ```
  323. Every GitHub release is archived on Zenodo under this concept DOI, which
  324. always resolves to the most recent version.
  325. ## License
  326. 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
  1. #!/usr/bin/env bash
  2. # Run on a SECOND, operator-controlled machine containing only the encrypted
  3. # archive. Identity is injected from the external secret manager on that host.
  4. # No production connection, Docker network, plaintext dump or host volume.
  5. set -euo pipefail
  6. umask 077
  7. if [[ $# -ne 1 ]]; then
  8. 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
  9. exit 2
  10. fi
  11. archive="$1"
  12. [[ -f "$archive" && -s "$archive" && ! -L "$archive" ]] || {
  13. echo 'Encrypted offsite archive is missing, empty or linked' >&2; exit 2;
  14. }
  15. [[ ! -L "$(dirname "$archive")" ]] || { echo 'Refusing linked archive directory' >&2; exit 2; }
  16. mode=$(stat -c '%a' "$archive")
  17. (( (8#$mode & 077) == 0 )) || { echo 'Offsite archive is readable by others' >&2; exit 2; }
  18. [[ "${EXPECTED_SHA256:-}" =~ ^[a-f0-9]{64}$ ]] || { echo 'Expected encrypted archive SHA-256 required' >&2; exit 2; }
  19. [[ "$(sha256sum "$archive" | awk '{print $1}')" == "$EXPECTED_SHA256" ]] || {
  20. echo 'Encrypted offsite archive differs from source receipt' >&2; exit 1;
  21. }
  22. [[ "${EXPECTED_SCHEMA_VERSION:-}" =~ ^[1-9][0-9]{0,2}$ ]] || {
  23. echo 'Expected positive reviewed schema version required' >&2; exit 2;
  24. }
  25. [[ "${EXPECTED_LEDGER:-}" =~ ^[1-9][0-9]*:[a-f0-9]{32}$ &&
  26. "${EXPECTED_LEDGER%%:*}" == "$EXPECTED_SCHEMA_VERSION" ]] || {
  27. echo 'Source migration checksum receipt/count must match schema version' >&2; exit 2;
  28. }
  29. [[ -n "${KICAD_BACKUP_AGE_IDENTITY:-}" && -n "${KICAD_BACKUP_AGE_RECIPIENT:-}" ]] || {
  30. echo 'Independent operator must provide authorized age identity through secret manager' >&2; exit 2;
  31. }
  32. for cmd in docker age age-keygen openssl mktemp; do command -v "$cmd" >/dev/null || { echo "Missing restore tool: $cmd" >&2; exit 2; }; done
  33. [[ -d /dev/shm ]] || { echo 'RAM-only key staging unavailable' >&2; exit 2; }
  34. tmp=$(mktemp -d /dev/shm/kicad-offsite-recovery.XXXXXXXX)
  35. target="kicad-offsite-restore-$(openssl rand -hex 6)"
  36. cleanup(){ docker rm -f "$target" >/dev/null 2>&1 || true; rm -rf -- "$tmp"; }
  37. trap cleanup EXIT
  38. printf '%s\n' "$KICAD_BACKUP_AGE_IDENTITY" > "$tmp/identity"
  39. chmod 600 "$tmp/identity"
  40. [[ "$(age-keygen -y "$tmp/identity")" == "$KICAD_BACKUP_AGE_RECIPIENT" ]] || {
  41. echo 'Independent recovery identity/recipient mismatch' >&2; exit 1;
  42. }
  43. password=$(openssl rand -hex 24)
  44. docker run --rm -d --network none --name "$target" \
  45. --tmpfs /var/lib/postgresql/data:rw,size=256m \
  46. --tmpfs /var/run/postgresql:rw,size=16m \
  47. --tmpfs /tmp:rw,size=16m \
  48. -e POSTGRES_USER=offsite_fixture -e POSTGRES_DB=offsite_fixture \
  49. -e "POSTGRES_PASSWORD=$password" postgres:17-alpine >/dev/null
  50. # Docker represents --tmpfs in HostConfig.Tmpfs rather than .Mounts.
  51. [[ $(docker inspect "$target" --format '{{index .HostConfig.Tmpfs "/var/lib/postgresql/data"}}') == *size=256m* ]] || {
  52. echo 'Temporary database is not RAM-backed; refusing decryption' >&2; exit 1;
  53. }
  54. ready=false
  55. for _ in $(seq 1 45); do
  56. # pg_isready alone is insufficient: the image bootstraps a temporary PG
  57. # server, shuts it down and starts the actual server.
  58. if docker logs "$target" 2>&1 | grep -q 'PostgreSQL init process complete; ready for start up' && \
  59. docker exec "$target" pg_isready -q -U offsite_fixture -d offsite_fixture; then
  60. ready=true; break
  61. fi
  62. sleep 1
  63. done
  64. [[ "$ready" == true ]] || { echo 'PostgreSQL final boot was not confirmed' >&2; exit 1; }
  65. # 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
  66. age -d -i "$tmp/identity" "$archive" |
  67. docker exec -i "$target" pg_restore --exit-on-error --no-owner --no-acl \
  68. -U offsite_fixture -d offsite_fixture >/dev/null
  69. query(){ docker exec "$target" psql -X -A -t -q -v ON_ERROR_STOP=1 \
  70. -U offsite_fixture -d offsite_fixture -c "$1"; }
  71. version=$(query 'SELECT max(version) FROM schema_migrations')
  72. [[ "$version" == "$EXPECTED_SCHEMA_VERSION" ]] || { echo 'Recovered schema version differs' >&2; exit 1; }
  73. ledger=$(query "SELECT count(*)::text || ':' || coalesce(md5(string_agg(version::text || ':' || checksum, '|' ORDER BY version)), '') FROM schema_migrations")
  74. if [[ "$ledger" != "$EXPECTED_LEDGER" ]]; then
  75. echo 'Recovered migration checksums differ from signed-off source receipt' >&2; exit 1
  76. fi
  77. 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')")
  78. [[ "$triggers" == 3 ]] || { echo 'OAuth security fences absent from restore' >&2; exit 1; }
  79. for table in devices projects project_client_grants '"users"' '"oauthClient"' '"oauthConsent"'; do
  80. count=$(query "SELECT count(*) FROM $table")
  81. [[ "$count" =~ ^[0-9]+$ ]] || { echo 'Metadata table unreadable after restore' >&2; exit 1; }
  82. done
  83. 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 in

Free to use. If it’s helped, pass it on.