Kicad MCP Pro

<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="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT License" /></a> <a href="https://doi.org/10.5281/zenodo.21283791"><img src="https://zenodo.org/badge/1255527274.svg" alt="DOI" /></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> <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> <p> <a href="https://pepy.tech/project/kicad-mcp-pro"><img src="https://static.pepy.tech/badge/kicad-mcp-pro" 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%20downloads" alt="npm total downloads" /></a> </p> <!-- parity-coverage-badge:start -->

<!-- parity-coverage-badge:end --> <p> <a href="https://www.buymeacoffee.com/oaslananka"><img src="https://img.shields.io/badge/sponsor-Buy%20me%20a%20coffee-ffdd00?logo=buymeacoffee&logoColor=black" alt="Buy me a coffee" /></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; see docs/agents/progressive-disclosure.md.

Telemetry and error reporting are disabled by default. Opt-in OpenTelemetry configuration is documented in docs/configuration.md, and privacy rules are documented in 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. 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 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
PyPI package	kicad-mcp-pro
npm wrapper	kicad-mcp-pro
MCP Registry name	io.github.oaslananka/kicad-mcp-pro
Version	4.16.0
OSS maturity report	docs/repo-maturity-report.md
OpenSSF evidence	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:

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 for setup and security details.

CLI (recommended)

Install the CLI once with uv, 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 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.

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

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 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/. 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

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
2. Client configuration
3. Runtime configuration
4. Tool reference
5. Workflows
6. Release process
7. Security and privacy
8. KiCad capability parity — how much of KiCad's programmatic surface this server drives
9. Error code catalog — stable error codes, retry classes, and recovery
10. Work-order audit — 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 gaps 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/.

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.

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:

uvx kicad-mcp-pro --help
npx kicad-mcp-pro --help

Fresh source checkout on supported Linux hosts:

./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 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:

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 for details and explicit agent selection.

Usage

Use kicad-mcp-pro --help to inspect CLI commands and docs/client-configuration.md to configure an MCP client. The generated tool catalog is available in 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 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, mcp.json	Generated portable plugin package with canonical skills and a version-pinned local MCP launcher.
.claude-plugin/plugin.json	Product-level plugin manifest for compatible agent runtimes and marketplace catalogs.
.mcp.json	Claude Code project-local MCP server configuration.
.codex/config.example.toml	Codex CLI MCP configuration example.
.vscode/mcp.example.json	VS Code / GitHub Copilot workspace MCP configuration example.
integrations/opencode/opencode.example.json	OpenCode project MCP configuration example.
.opencode/skills/	OpenCode-native mirrored skill definitions.
docs/agent-runtime-config.md	Agent runtime setup and validation matrix.
skills/kicad-design-review/SKILL.md	Comprehensive KiCad design review skill.
skills/pcb-design/SKILL.md	PCB design, layout inspection, placement, routing, stackup, and board-quality workflow.
skills/drc-check/SKILL.md	ERC/DRC execution, triage, waiver review, and revalidation workflow.
skills/fabrication-output/SKILL.md	Manufacturing export, DFM, release evidence, and fabrication-package workflow.
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. Common local starts are:

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:

corepack 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, 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.

The project uses a Taskfile.yml for common development commands. After cloning the repository:

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 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 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.

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 for full metadata):

@software{aslan_kicad_mcp_pro,
  author  = {Aslan, Osman},
  title   = {KiCad MCP Pro},
  license = {MIT},
  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 is available under the MIT License.