KiCad MCP Server 🔌📐

An implementation of the Model Context Protocol (MCP) server for KiCad 9.0+, enabling Large Language Models (LLMs) like Claude to inspect, edit, analyze, and render PCB layouts in real-time.

It leverages the official kicad-python API to communicate with running KiCad instances over local Unix domain sockets or Windows named pipes.

---

🚀 Key Features

This server exposes 14 specialized modules providing comprehensive control over the board layout:

Module	Description	Key Tools
🎛️ Board	Inspect/update PCB configurations, units, and canvas settings	get_board_info, get_board_stackup, set_active_layer, undo_transaction
🧩 Footprints	Manage component properties, placements, and pads	get_footprints, move_footprint, set_footprint_property, delete_footprints
⚡ Tracks & Vias	List, route, resize, and remove traces and vias	get_tracks, create_track, get_vias, create_via, delete_tracks_in_rect
🗺️ Zones	Control copper pours, fill/unfill, and rule boundaries	get_zones, create_zone, refill_zones
🌐 Nets	Import netlists, manage classes, and trace connectivity	get_nets, get_net_classes, import_netlist
🔤 Text	Add and style free-standing board text labels and textboxes	get_text, create_text, create_textbox, delete_text
🎨 Shapes	Draw graphic segments, rects, circles, and polygons on user layers	get_shapes, create_shape
📏 Dimensions	Place precise dimension and measurement markings	get_dimensions, create_dimension
👥 Groups	Read structural component groupings (KiCad 10+)	get_groups
🎯 Selection	Read active selection, select footprints, and invoke actions	get_selection, select_footprints, run_action
👁️ Appearance	Adjust layer visibility, contrast modes, ratsnest lines, and flip view	get_editor_appearance, set_board_flip, set_inactive_layer_display
📦 Exports	Export manufacturing files (Gerbers, drills, position, ODB++, PDF, STEP)	export_gerbers, export_drill, export_position, export_3d, export_pdf
📸 Screenshots	Render visual PNG screenshots of the board or specific selection	get_board_screenshot, get_selection_screenshot
💻 CLI Wrapper	Headless CLI automation for schematics, ERC, DRC, and more	run_kicad_cli, run_erc, run_drc, export_schematic_pdf, export_schematic_netlist

---

📋 Prerequisites

1. KiCad 9.0 or higher must be installed and running.
2. Enable the IPC API inside KiCad:
   • Go to Preferences ➔ Preferences...
   • Navigate to Plugins
   • Check the Enable KiCad IPC API box.
3. Python 3.10+ (tested on Python 3.10 through 3.14).

---

⚙️ Installation & Setup

We recommend using uv for fast and isolated environment setup.

1. Clone the Repository

git clone https://github.com/brovk2008/Kicad-MCP-server.git
cd Kicad-MCP-server

2. Set Up the Virtual Environment

# Using uv (recommended)
uv venv
uv pip install -e .

# Or using standard pip
python -m venv .venv
source .venv/bin/activate  # Or `.venv\Scripts\activate` on Windows
pip install -e .

Note: The project automatically applies a dynamic Protobuf descriptor pool patch to ensure compatibility with kicad-python 0.7.1 on Python 3.14.

---

🛠️ MCP Configuration

To use this server with Claude Desktop, add the configuration snippet below to your Claude configuration file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json

Configuration Snippet

{
  "mcpServers": {
    "kicad-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--package",
        "kicad-mcp",
        "kicad-mcp"
      ],
      "cwd": "C:/Users/techp/Downloads/more projects/Kicad mcp",
      "env": {
        "KICAD_API_SOCKET": "ipc:///tmp/kicad/api.sock"
      }
    }
  }
}

(Adjust the cwd directory to point to your local installation path. For Windows, the socket path defaults to ipc://%TEMP%\\kicad\\api.sock if not explicitly set).

---

🧪 Running Tests

A test suite is included to verify unit conversions, coordinate mappings, and error wrappers:

# Activate your virtual environment and run:
pytest tests/unit/

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.