KiCad MCP Pro

What is KiCad MCP Pro about?

KiCad MCP Pro provides a Model Context Protocol (MCP) server that lets AI agents such as Claude, Cursor, or GitHub Copilot drive KiCad’s design workflow. It bridges AI‑generated commands with KiCad’s native engines, covering schematic creation, PCB routing, rule checks, design‑for‑manufacturing evaluation, and export of fabrication files.

How to use KiCad MCP Pro?

1. Install the package via npm (recommended): npx -y kicad-mcp-pro.
2. Start the server using one of the supported transports, e.g.:

   npx -y kicad-mcp-pro --transport stdio
   # or HTTP streamable interface
   npx -y kicad-mcp-pro --transport streamable-http --host 127.0.0.1 --port 3334
   

3. Configure your AI agent to connect to the server (provide the MCP endpoint and protocol version).
4. Invoke tools through the MCP API – tools/list, kicad_get_project_info, or any of the skill‑specific commands defined under skills/.
5. Review the generated outputs (ERC/DRC reports, DFM estimations, Gerber files) before committing to fabrication.

Key Features

• Full‑stack KiCad automation: schematic capture, PCB layout, rule validation, DFM, BOM, and manufacturing export.
• Multi‑agent support: works with Claude, Cursor, GitHub Copilot, and any MCP‑compatible AI.
• Two transport modes: stdio for local piping and Streamable HTTP for networked clients.
• Extensible skill catalog: ready‑made skill definitions for design review, DRC checking, and fabrication output.
• Telemetry opt‑in: disabled by default, with OpenTelemetry configuration available.
• Compatibility matrix: drives ~76 % of KiCad’s programmatic surface (see capability‑parity report).
• Cross‑platform packaging: available as a Python package (kicad-mcp-pro), npm wrapper, and Tauri desktop GUI.

Use Cases

• AI‑assisted design iteration: let a LLM suggest component placement, routing improvements, or schematic additions and have the server apply them instantly.
• Automated pre‑flight checks: run ERC/DRC and DFM analyses on every commit in a CI pipeline.
• Rapid BOM and manufacturing package generation: generate up‑to‑date BOMs and Gerber files for JLCPCB, DigiKey, Mouser, etc., directly from AI prompts.
• Educational tooling: students can ask an AI to explain a rule violation and see the server highlight the issue in KiCad.
• Custom workflow integration: embed KiCad actions into larger PLM or ERP systems via the MCP HTTP endpoint.

FAQ

Q: Which transports are supported? A: stdio and Streamable HTTP. HTTP can be made stateful with KICAD_MCP_STATEFUL_HTTP=1.

Q: Do I need a KiCad license? A: KiCad is free and open source; the server interacts with the installed KiCad binaries.

Q: Is this a replacement for formal sign‑off? A: No. It provides fast first‑pass estimates (≈5‑10 % accuracy) and should be followed by qualified human review before fabrication.

Q: How do I enable telemetry? A: Telemetry is disabled by default. Enable OpenTelemetry by editing docs/configuration.md and setting the appropriate environment variables.

Q: Can I run the server inside a container? A: Yes. The server contract is defined in server.json; you can containerise the Python package or use the npm wrapper inside a Docker image.

Q: Where can I find the full tool reference? A: See docs/tools-reference.generated.md for a catalog of all exposed MCP tools.

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.

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.

Project identity

Field	Value
Canonical repository	oaslananka/kicad-mcp
PyPI package	kicad-mcp-pro
npm wrapper	kicad-mcp-pro
MCP Registry name	io.github.oaslananka/kicad-mcp-pro
Version	3.20.0
OSS maturity report	docs/repo-maturity-report.md
OpenSSF evidence	docs/openssf-evidence.md

Quick Start

Desktop App

Download the latest installer from the GitHub releases page. The Tauri desktop app starts the Python dashboard server automatically and opens the GUI at http://127.0.0.1:3334/ui.

CLI

uvx kicad-mcp-pro init
uvx kicad-mcp-pro tray
uvx kicad-mcp-pro dashboard --open
uvx kicad-mcp-pro --transport streamable-http --port 3334

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.3%), 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/.

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
• Content-Type: application/json
• MCP-Protocol-Version: 2025-11-25 after initialization
• MCP-Session-Id on follow-up requests when KICAD_MCP_STATEFUL_HTTP=1

By default Streamable HTTP is stateless, so ChatGPT-style connectors can initialize and call tools/list without a session-header injection proxy. Set KICAD_MCP_STATEFUL_HTTP=1 to require session IDs after initialize.

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

corepack pnpm run dev:doctor -- --ci
uvx kicad-mcp-pro --help
npx kicad-mcp-pro --help

For source checkouts, corepack pnpm run dev:doctor validates Node, pnpm, Python, uv, MCP server CLI startup/version reporting, fixture corpus, protocol schemas, common development ports, and optional Cloudflare tunnel tooling. If repository commands fail with a uv required-version mismatch before Python starts, run kicad-mcp-pro doctor --json and check the uv_version result. The checkout's uv.toml pins the supported uv release; switch to that version (for example uv self update 0.10.8 when required) and rerun uv sync --all-extras --frozen.

Package metadata

The canonical metadata source of truth is server.json, which defines the MCP server contract. It is synchronized with pyproject.toml and verified in CI via pnpm run metadata:check.

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
.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.
opencode.example.jsonc	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 local 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.

License

KiCad MCP Pro is available under the MIT License.