# kicad-mcp-kipy

**KiCad MCP server for KiCad 10** — powered by [kipy](https://pypi.org/project/kicad-python/), the official KiCad Python API.

Connects AI assistants (Claude, Bob, etc.) to a running KiCad 10 instance via the [Model Context Protocol](https://modelcontextprotocol.io/), enabling real-time inspection and control of schematics and PCB layouts.

## Why kicad-mcp-kipy?

| | [kicad-mcp (Huaqiu)](https://github.com/Huaqiu-Electronics/kicad-mcp) | **kicad-mcp-kipy** |
|---|---|---|
| KiCad 10 support | ❌ (KiCad 9 JSON API) | ✅ (KiCad 10 Protobuf API) |
| macOS process detection | ❌ ([Issue #3](https://github.com/Huaqiu-Electronics/kicad-mcp/issues/3)) | ✅ |
| Dependencies | 115 packages | ~40 packages |
| Python API | Custom JSON/NNG | kipy (official KiCad bindings) |

## Requirements

- KiCad 10.x (macOS / Linux / Windows)
- Python 3.11+
- [uv](https://github.com/astral-sh/uv) (recommended) or pip

## Installation

### Using uvx (recommended — no install needed)

```bash
uvx kicad-mcp-kipy
```

### Using pip

```bash
pip install kicad-mcp-kipy
kicad-mcp-kipy
```

## Setup

### 1. Enable KiCad IPC API

In KiCad's Schematic Editor or PCB Editor:

**Preferences → Preferences → Scripting → Enable IPC API** ✅

### 2. Register in your MCP client (Bob / Claude Desktop)

**.bob/mcp.json** (workspace-level):

```json
{
  "mcpServers": {
    "kicad": {
      "command": "uvx",
      "args": ["kicad-mcp-kipy"]
    }
  }
}
```

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "kicad": {
      "command": "uvx",
      "args": ["kicad-mcp-kipy"]
    }
  }
}
```

### 3. Open a project in KiCad

Open your schematic or PCB file in KiCad **before** connecting — the IPC API is only active when an editor is open.

## Available Tools

### General
| Tool | Description |
|---|---|
| `get_kicad_version` | Get running KiCad version |
| `get_open_documents` | List open schematic / PCB files |
| `run_action` | Execute a KiCad menu action (e.g. `"zoom_fit_in_window"`) |

### Schematic
| Tool | Description |
|---|---|
| `schematic_get_symbols` | Get all symbols (reference, value, position) |
| `schematic_get_labels` | Get all net labels |
| `schematic_get_title_block` | Get title block info |
| `schematic_get_as_string` | Get schematic as KiCad S-expression text |
| `schematic_get_hierarchy` | Get hierarchical sheet structure |
| `schematic_save` | Save the schematic |

### PCB
| Tool | Description |
|---|---|
| `pcb_get_footprints` | Get all footprints (reference, value, position, layer) |
| `pcb_get_tracks` | Get all tracks (start, end, layer, width) |
| `pcb_get_vias` | Get all vias (position, drill size) |
| `pcb_get_nets` | Get all nets (name, number) |
| `pcb_get_enabled_layers` | Get enabled layer list |
| `pcb_get_stackup` | Get board stackup (layer structure, thickness) |
| `pcb_get_title_block` | Get PCB title block info |
| `pcb_get_as_string` | Get PCB as KiCad S-expression text |
| `pcb_save` | Save the PCB |

## How it works

```
AI Assistant (MCP Client)
    ↕  stdio (JSON-RPC)
kicad-mcp-kipy (MCP Server)
    ↕  pynng / NNG IPC socket  (/tmp/kicad/api.sock)
KiCad 10 IPC API Server (built-in)
    ↕  C++ SDK
KiCad Schematic / PCB Editor
```

KiCad 10 exposes a Protobuf-based IPC API over a local NNG socket. `kipy` provides Python bindings for this API. This server wraps those bindings as MCP tools.

## Development

```bash
git clone https://github.com/mnori0211/kicad-mcp-kipy
cd kicad-mcp-kipy
uv sync
uv run kicad-mcp-kipy
```

## Related

- [kipy (kicad-python)](https://pypi.org/project/kicad-python/) — Official KiCad Python API bindings
- [kicad-mcp (Huaqiu)](https://github.com/Huaqiu-Electronics/kicad-mcp) — Alternative MCP server (KiCad 9)
- [Model Context Protocol](https://modelcontextprotocol.io/)

## License

MIT — see [LICENSE](LICENSE)