Metadata-Version: 2.4
Name: kicad-mcp-pro
Version: 3.2.1
Summary: A Model Context Protocol server for KiCad EDA workflows.
Project-URL: Homepage, https://github.com/oaslananka/kicad-mcp-pro
Project-URL: Documentation, https://oaslananka-lab.github.io/kicad-mcp-pro
Project-URL: Repository, https://github.com/oaslananka-lab/kicad-mcp-pro
Project-URL: Bug Tracker, https://github.com/oaslananka-lab/kicad-mcp-pro/issues
Project-URL: Changelog, https://github.com/oaslananka-lab/kicad-mcp-pro/blob/main/CHANGELOG.md
Project-URL: Funding, https://github.com/sponsors/oaslananka
Author: Osman Aslan
License: MIT
Keywords: ai,eda,eda-automation,gerber-export,kicad,llm,mcp,pcb,pcb-design,schematic
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: anyio>=4.4.0
Requires-Dist: authlib>=1.6.11
Requires-Dist: kicad-python<0.8,>=0.6
Requires-Dist: kicad-sch-api<0.6,>=0.5.0
Requires-Dist: mcp[cli]>=1.23.0
Requires-Dist: pydantic-settings>=2.3.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: rich>=13.7.0
Requires-Dist: structlog>=24.2.0
Requires-Dist: typer>=0.12.0
Provides-Extra: components
Requires-Dist: gql>=3.5.0; extra == 'components'
Requires-Dist: httpx>=0.27.0; extra == 'components'
Provides-Extra: dev
Requires-Dist: bandit>=1.7.9; extra == 'dev'
Requires-Dist: hypothesis>=6.100.0; extra == 'dev'
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.2.9; extra == 'dev'
Requires-Dist: mkdocs-glightbox>=0.4.0; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5.32; extra == 'dev'
Requires-Dist: mkdocs-minify-plugin>=0.8.0; extra == 'dev'
Requires-Dist: mkdocs-redirects>=1.2.1; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.25.0; extra == 'dev'
Requires-Dist: mutmut>=3.0.0; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pyright>=1.1.390; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
Requires-Dist: pytest-testmon>=2.1.1; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6.0; extra == 'dev'
Requires-Dist: pytest>=8.2.0; extra == 'dev'
Requires-Dist: radon>=6.0.1; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: safety>=3.2.0; extra == 'dev'
Requires-Dist: vulture>=2.11; extra == 'dev'
Requires-Dist: zizmor>=1.24.1; extra == 'dev'
Provides-Extra: freerouting
Requires-Dist: docker>=7.0.0; extra == 'freerouting'
Provides-Extra: http
Requires-Dist: httpx>=0.27.0; extra == 'http'
Requires-Dist: uvicorn[standard]>=0.30.0; extra == 'http'
Provides-Extra: simulation
Requires-Dist: numpy>=1.26.0; extra == 'simulation'
Provides-Extra: vcs
Requires-Dist: gitpython<4.0.0,>=3.1.49; extra == 'vcs'
Description-Content-Type: text/markdown

# KiCad MCP Pro Server

<!-- mcp-name: io.github.oaslananka-lab/kicad-mcp-pro -->

[![PyPI](https://img.shields.io/pypi/v/kicad-mcp-pro.svg)](https://pypi.org/project/kicad-mcp-pro/)
[![CI](https://github.com/oaslananka-lab/kicad-mcp-pro/actions/workflows/ci.yml/badge.svg)](https://github.com/oaslananka-lab/kicad-mcp-pro/actions/workflows/ci.yml)
[![Docs](https://github.com/oaslananka-lab/kicad-mcp-pro/actions/workflows/docs.yml/badge.svg)](https://github.com/oaslananka-lab/kicad-mcp-pro/actions/workflows/docs.yml)
[![Release](https://github.com/oaslananka-lab/kicad-mcp-pro/actions/workflows/release.yml/badge.svg)](https://github.com/oaslananka-lab/kicad-mcp-pro/actions/workflows/release.yml)
[![Codecov](https://codecov.io/gh/oaslananka-lab/kicad-mcp-pro/branch/main/graph/badge.svg)](https://codecov.io/gh/oaslananka-lab/kicad-mcp-pro)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/oaslananka-lab/kicad-mcp-pro/badge)](https://scorecard.dev/viewer/?uri=github.com/oaslananka-lab/kicad-mcp-pro)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](pyproject.toml)
[![KiCad 10](https://img.shields.io/badge/KiCad-10-success.svg)](https://www.kicad.org)
[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-oaslananka-yellow?logo=buy-me-a-coffee)](https://buymeacoffee.com/oaslananka)

KiCad MCP Pro is a Model Context Protocol server for KiCad PCB and schematic workflows. It gives agents project setup, schematic editing, PCB inspection and edits, validation gates, DFM checks, SI/PI helpers, simulation helpers, and release-gated manufacturing export.

Use it with Claude Desktop, Claude Code, Cursor, VS Code, Codex, or any MCP-compatible client.

Canonical repository: https://github.com/oaslananka-lab/kicad-mcp-pro

Personal showcase mirror: https://github.com/oaslananka/kicad-mcp-pro

## Quick Start

Install and run with `uvx`:

```bash
uvx kicad-mcp-pro --help
uvx kicad-mcp-pro health --json
uvx kicad-mcp-pro doctor --json
uvx kicad-mcp-pro serve
```

Or install with `pip`:

```bash
pip install kicad-mcp-pro
kicad-mcp-pro --help
kicad-mcp-pro health --json
kicad-mcp-pro serve
```

The default no-subcommand invocation still starts the stdio MCP server for
backward compatibility. `health --json` is safe to run when KiCad is not
running; it reports KiCad IPC as deferred instead of crashing. `doctor --json`
adds deeper CLI and IPC diagnostics for launchers such as `kicad-studio`.

## Minimal MCP Config

Use an absolute KiCad project path:

```json
{
  "servers": {
    "kicad": {
      "type": "stdio",
      "command": "uvx",
      "args": ["kicad-mcp-pro"],
      "env": {
        "KICAD_MCP_PROJECT_DIR": "/absolute/path/to/your/kicad-project",
        "KICAD_MCP_WORKSPACE_ROOT": "/absolute/path/to/your/workspace",
        "KICAD_MCP_PROFILE": "pcb_only"
      }
    }
  }
}
```

More client examples:

- [Client configuration](docs/client-configuration.md)
- [Claude Desktop](docs/integration/claude-desktop.md)
- [Cursor](docs/integration/cursor.md)
- [Claude Code](docs/integration/claude-code.md)
- [KiCad Studio](docs/integration/kicad-studio.md)

## What It Does

- Project-aware setup with safe path handling and recent-project discovery.
- PCB tools for board state, tracks, vias, footprints, layers, zones, placement, and sync.
- Schematic tools for symbols, wires, labels, buses, annotation, templates, routing, and IPC reload.
- Validation gates for schematic quality, connectivity, PCB quality, placement, transfer, DFM, and manufacturing.
- Gated release handoff through `export_manufacturing_package()`.
- Export tools for Gerber, drill, BOM, PDF, netlist, STEP, render, pick-and-place, IPC-2581, SVG, and DXF.
- SI, PI, EMC, routing, simulation, library, and version-control helper surfaces.
- Server profiles such as `minimal`, `pcb_only`, `schematic_only`, `manufacturing`, `analysis`, and `agent_full`.
- Machine-readable CLI diagnostics for editors and MCP clients.

## Capability Status

Capabilities are verified at different levels depending on test coverage and runtime dependencies.
See [Capability Verification Levels](docs/status/capability-levels.md) for the current truth table.

## Common Workflow

```text
kicad_set_project()
project_get_design_spec()
sch_build_circuit()
pcb_sync_from_schematic()
project_quality_gate_report()
export_manufacturing_package()
```

Demo media guidance lives in [docs/demo-media.md](docs/demo-media.md).

## Documentation

- [Installation](docs/installation.md)
- [Configuration](docs/configuration.md)
- [Tools reference](docs/tools-reference.md)
- [Troubleshooting](docs/troubleshooting.md)
- [FAQ](docs/faq.md)
- [API stability](docs/api-stability.md)
- [Release process](docs/release-process.md)
- [Maintenance policy](docs/maintenance-policy.md)
- [Workflow security](docs/workflow-security.md)
- [Publishing](docs/publishing.md)
- [Release integrity](docs/security/release-integrity.md)
- [Docker install](docs/install/docker.md)
- [Client config generator](docs/install/client-config-generator.md)
- [Security threat model](docs/security/threat-model.md)
- [Architecture decisions](docs/adr/README.md)
- [Comparison](docs/comparison.md)

## Repository Operations

Normal CI and security workflows run on pull requests, pushes, and merge queue
events. Release, publish, mirroring, deployment, and token-backed jobs remain
guarded behind explicit repository checks and protected environments.

The project uses Dependabot, Renovate, CodeQL, Gitleaks, Trivy, OpenSSF
Scorecard, Codecov, release-please, SBOM generation, Sigstore signing, and
GitHub artifact attestations for release hardening.

Operational references:

- [Repository operations](docs/repository-operations.md)
- [Publishing](docs/publishing.md)
- [Jules automation](docs/automation/jules.md)
- [Autonomy model](docs/autonomy.md)
- [Doppler setup](docs/doppler-setup.md)
- [Branch protection](docs/branch-protection.md)

Jules-based fixer automation is restricted to the canonical organization
repository. Jules may open or update fix PRs, but it must not publish packages,
registries, releases, SBOMs, signatures, or attestations, and it must not merge
without human review.

## Contributing and Support

- [Contributing](CONTRIBUTING.md)
- [Support](SUPPORT.md)
- [Governance](GOVERNANCE.md)
- [Security policy](SECURITY.md)
- [Roadmap](ROADMAP.md)
- [Changelog](CHANGELOG.md)
