KiPilot MCP

KiPilot is a Python-based Model Context Protocol (MCP) server that connects MCP-aware clients, such as GitHub Copilot in VS Code, to a user-controlled KiCad 10.x GUI session through the official kicad-python IPC binding.

The server runs over stdio, exposes PCB-first MCP tools plus a build-gated schematic subset, and is designed for live KiCad workflows where the user keeps full control of the GUI session.

Usage Videos

Usage videos are available at kipilot.org/galery.html.

Documentation

Public project documentation is available at kipilot.org/docs.html.

Overview

KiPilot exists to let an MCP client inspect and manipulate KiCad documents that are already open in the user-controlled GUI session, with PCB workflows as the primary baseline.

Uses the official KiCad IPC path through kicad-python
Runs as a stdio MCP server for VS Code and similar hosts
Supports read-heavy PCB workflows plus guarded mutation tools
Adds a source-build-gated schematic surface for hierarchy, hit-testing, metadata mutation, and export workflows where the running KiCad build exposes the newer schematic IPC handlers
Adds selected higher-level MCP helpers on top of raw IPC primitives, such as a real footprint side-flip workflow that mirrors child artwork and swaps paired layers
Keeps KiCad as a separate, user-launched GUI application

This repository targets the KiCad 10 PCB-first baseline. It does not aim to be a 1:1 wrapper over every public method exposed by the KiCad Python binding.

Where the raw IPC surface does not expose a single native operation but the underlying board objects are still mutable, KiPilot may provide a higher-level MCP tool that composes those lower-level capabilities into one agent-friendly action. The current example is kicad_flip_footprint, which performs a real mirrored side flip even though the KiCad binding does not expose one direct footprint-flip call.

Current Scope

Implemented MCP surface includes:

MCP stdio server entry point
Async-friendly KiCad IPC client wrapper around kipy.KiCad
Connectivity and version checks such as ping_kicad and get_kicad_version
Board and document inspection tools for open documents, outlines, stackup, footprints, nets, pads, tracks, vias, zones, graphics, dimensions, groups, reference images, barcodes, text, text geometry, project text variables, project net classes, origins, title blocks, selection state, and connectivity
Filtered lookup tools for footprints, footprint-scoped pads, nets, net classes, and connected items
Guarded mutation tools for visible layers, active layer, enabled layers, footprint move/rotate/flip, footprint pad net reassignment, origins, title block fields, board text, track creation, via creation, item updates, track geometry, zone outlines, item deletion, zone refill, board revert, and board save
Schematic hierarchy, netlist, hit-testing, page-settings, title-block, metadata-mutation, and export tools when the active KiCad runtime exposes schematic IPC support
Unit tests for IPC connection and error-handling behavior

Committed baseline:

GUI IPC only
PCB editor first
Initial schematic inspection, hit-testing, metadata mutation, and export workflows are supported only when the running KiCad build exposes the newer schematic IPC surface
Read-heavy workflows first, validated mutation workflows second
No committed headless automation scope

Schematic MCP Surface

The schematic surface is intentionally smaller and more runtime-dependent than the PCB surface.

Available schematic tools:

Inspection: kicad_sch_get_hierarchy, kicad_sch_get_netlist, kicad_sch_get_page_settings, and kicad_sch_get_title_block
Inspection geometry: kicad_sch_hit_test
Guarded metadata mutation: kicad_sch_set_page_settings and kicad_sch_set_title_block
Plot export: kicad_sch_export_svg, kicad_sch_export_dxf, kicad_sch_export_pdf, and kicad_sch_export_ps
File export: kicad_sch_export_netlist and kicad_sch_export_bom

Important export semantics:

kicad_sch_export_svg, kicad_sch_export_dxf, and kicad_sch_export_ps take output_dir because KiCad writes one file per plotted sheet into a directory.
kicad_sch_export_pdf takes output_file because KiCad writes one PDF file to a file path.
kicad_sch_export_netlist and kicad_sch_export_bom also take output_file because they produce single file outputs.
When you want a full schematic export, plot_all=true with omitted plot_pages is the safest default unless you already know the exact sheet-instance paths to filter.
In this environment, live end-to-end schematic MCP validation succeeded against a locally built kicad-master eeschema snapshot. The installed official KiCad 10.0.1 build did not expose the same reliable external schematic IPC behavior, so treat the schematic surface as source-build-gated rather than universally available across all KiCad 10 installations.

Requirements

KiCad 10.x installed locally
A running KiCad GUI instance with IPC API support
Python 3.11+ for source installs and local ZIP builds
Git for source installs

Use a stable CPython release such as 3.11, 3.12, or 3.13. Avoid preview or alpha Python interpreters because the native dependency chain may not publish wheels for them yet.

The Windows ZIP release bundles its own Python runtime for the server process, so local Python is not required when you install from the downloadable Windows artifact.

Quick Start

Choose the installation path that fits your workflow:

Windows ZIP release if you want a ready-to-run Windows MCP server without managing Python locally
Source install if you want to inspect, modify, or develop the server from this repository

Windows ZIP release

Download the latest Windows release ZIP from GitHub Releases, extract it, and point your MCP host at kipilot-mcp.exe.

Latest release: https://github.com/belaszalontai/kipilot-mcp/releases/latest
Artifact name pattern: kipilot-mcp-<version>-windows-x64.zip
The ZIP contains the stdio server executable plus its bundled runtime

Example VS Code MCP configuration using the extracted Windows ZIP:

{
	"servers": {
		"kipilot-mcp": {
			"type": "stdio",
			"command": "C:\\Tools\\kipilot-mcp-<version>-windows-x64\\kipilot-mcp.exe",
			"env": {
				"KIPILOT_KICAD_CLIENT_NAME": "kipilot-mcp",
				"KIPILOT_KICAD_TIMEOUT_MS": "60000",
				"KIPILOT_LOG_LEVEL": "INFO",
				"KIPILOT_LOG_FILE": ".logs/kipilot-mcp.log"
			}
		}
	}
}

Do not double-click the executable for normal use. Let your MCP host start it so stdio stays attached to the host.

Source install

Clone the public repository:

git clone https://github.com/belaszalontai/kipilot-mcp.git
cd kipilot-mcp

Windows helper

On Windows, the repository includes a convenience script that creates .venv when needed, installs the runtime package, applies conservative default environment variables, and can start the server for manual checks:

.\start-kipilot-mcp.ps1 -SkipRun

Run without -SkipRun to start the server process directly from a terminal:

.\start-kipilot-mcp.ps1

For VS Code, Claude Desktop, and other MCP hosts, prefer configuring the host to launch python -m kipilot_mcp.server directly from the prepared environment. That keeps the stdio server command explicit and easy to audit.

Manual install

A virtual environment is recommended for dependency isolation, but it is not a KiPilot-specific requirement. If you already manage Python environments another way, point your MCP host at that interpreter instead.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install .

For development and tests, install in editable mode with development dependencies:

python -m pip install -e ".[dev]"

Start KiCad yourself, open the target hardware project, and open the PCB Editor before using board-aware MCP tools.

Configuration

The IPC connection uses KiCad's official API endpoint. On Windows this is a named pipe; on macOS and Linux it is a Unix domain socket. When KiCad launches an API plugin it provides these environment variables:

$env:KICAD_API_SOCKET = "..."
$env:KICAD_API_TOKEN = "..."

When the server is launched from VS Code rather than from KiCad, those variables may not be present. In that case kicad-python falls back to the default platform-dependent IPC endpoint, which is easiest to work with when only one KiCad instance is open.

KiPilot-specific settings:

$env:KIPILOT_KICAD_CLIENT_NAME = "kipilot-mcp"
$env:KIPILOT_KICAD_TIMEOUT_MS = "60000"
$env:KIPILOT_ENABLE_MUTATIONS = "0"
$env:KIPILOT_COMMIT_MESSAGE_PREFIX = "KiPilot MCP"
$env:KIPILOT_LOG_LEVEL = "INFO"
$env:KIPILOT_LOG_FILE = ".logs/kipilot-mcp.log"

Operational notes:

KIPILOT_ENABLE_MUTATIONS=0 keeps live board writes disabled by default
dry_run=true previews remain available even when writes are disabled
destructive tools such as revert and delete still require force=true
logs go to stderr by default so stdout stays clean for MCP traffic

Running The Server

After a source installation, run:

kipilot-mcp

or:

python -m kipilot_mcp.server

Example VS Code MCP configuration for a source install:

{
	"servers": {
		"kipilot-mcp": {
			"type": "stdio",
			"command": "${workspaceFolder}\\.venv\\Scripts\\python.exe",
			"args": ["-m", "kipilot_mcp.server"],
			"env": {
				"KIPILOT_KICAD_CLIENT_NAME": "kipilot-mcp",
				"KIPILOT_KICAD_TIMEOUT_MS": "60000",
				"KIPILOT_LOG_LEVEL": "INFO",
				"KIPILOT_LOG_FILE": ".logs/kipilot-mcp.log"
			}
		}
	}
}

If your KiCad setup requires an explicit API socket or token, add KICAD_API_SOCKET and KICAD_API_TOKEN to the same env block.

The bundled start-kipilot-mcp.ps1 script is useful for first-run setup and manual terminal checks on Windows. If you use the downloadable Windows ZIP, point the MCP host at kipilot-mcp.exe instead of the Python command. For source installs, MCP host configuration should normally use the direct Python command shown above so the host owns process startup and environment values.

Development

Install development dependencies:

python -m pip install -e ".[dev]"

Run tests:

python -m pytest

Run linting:

python -m ruff check .

Build the Windows ZIP release locally:

.\build-windows-zip.ps1 -ForceInstall -Clean

That script creates a versioned archive at artifacts/kipilot-mcp-<version>-windows-x64.zip, includes README.md and LICENSE inside the archive, and is the same build path used by the GitHub Actions release workflow.

Release process checklist: see RELEASE-CHECKLIST.md.

Repository Layout

.
|-- agent-test/
|   |-- .github/
|   |-- .logs/
|   |-- .vscode/
|   `-- README.md
|-- src/
|   `-- kipilot_mcp/
|       |-- __init__.py
|       |-- config.py
|       |-- errors.py
|       |-- ipc_client.py
|       |-- ipc_client_core.py
|       |-- ipc_client_pcb.py
|       |-- ipc_client_sch.py
|       |-- lookups.py
|       |-- serializers.py
|       `-- server.py
|-- tests/
|   `-- test_ipc_client.py
|-- KiPilot.svg
|-- build-windows-zip.ps1
|-- pyproject.toml
|-- pyinstaller_entry.py
|-- README.md
`-- start-kipilot-mcp.ps1

The `agent-test/` Folder

The agent-test/ directory is a small standalone VS Code test workspace for validating the MCP server from the perspective of a real Copilot agent setup.

Its purpose is to provide:

a clean workspace separate from the main source tree
a ready-made .vscode/mcp.json configuration that points to the sibling KiPilot server
custom Copilot agent and instruction files for KiCad-focused testing
a controlled workspace for end-to-end MCP validation

Open agent-test/ in a separate VS Code window when you want to test the full agent workflow end to end without mixing that setup into the main development workspace.

References

Capability Mapping

The current capability map for the server target is documented in .github/kicad-api-capabilities.md. Use that file as the source of truth for deciding which MCP tools belong in the KiCad 10 baseline, which ones need stronger validation, and which ones are version-gated for future KiCad releases.