Installation

Prerequisites

• Python 3.10 or newer
• uv package manager
• KiCad 9.0+ (for kicad-cli features)
• Git

Clone and install

git clone https://git.supported.systems/MCP/kicad-mcp.git
cd kicad-mcp
make install

make install uses uv to create a virtual environment and install all dependencies.

Configure your environment

Copy the example environment file and edit it with your paths:

cp .env.example .env

At minimum, set KICAD_SEARCH_PATHS to the directories where your KiCad projects live:

KICAD_SEARCH_PATHS=~/Documents/KiCad,~/Electronics

See Configuration for the full list of environment variables.

Connect to Claude Desktop

Add mckicad to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "kicad": {
      "command": "/ABSOLUTE/PATH/TO/kicad-mcp/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/TO/kicad-mcp/main.py"]
    }
  }
}

Replace the paths with absolute paths to your clone. Use the Python binary inside the .venv directory that make install created.

You can also pass environment variables directly in the client config:

{
  "mcpServers": {
    "kicad": {
      "command": "/ABSOLUTE/PATH/TO/kicad-mcp/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/TO/kicad-mcp/main.py"],
      "env": {
        "KICAD_SEARCH_PATHS": "/home/user/Electronics,/home/user/PCB"
      }
    }
  }
}

Restart Claude Desktop after editing the configuration.

Alternative: run directly

mckicad declares a console script entry point, so you can also run it with:

uv run mckicad

Or from the project directory:

uv run python main.py

Verify installation

After connecting, ask your AI client something like:

List all my KiCad projects

If the server is running and configured correctly, it will scan your search paths and return a list of .kicad_pro files.

Optional: FreeRouting (autorouting)

For automated PCB routing, install FreeRouting:

1. Download the JAR from freerouting.app
2. Place it at one of the auto-detected paths: ~/freerouting.jar, /usr/local/bin/freerouting.jar, or /opt/freerouting/freerouting.jar
3. Install a Java runtime (java must be on your PATH)
4. Verify with the check_routing_capability tool
5. Or set FREEROUTING_JAR_PATH in your .env file to an explicit path

Development commands

Command	Description
make install	Install dependencies with uv
make run	Start the MCP server
make test	Run all tests
make lint	Lint with ruff + mypy
make format	Auto-format with ruff
make build	Build package
make clean	Remove build artifacts