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: autorouting

For automated PCB routing, install freeroute, a native-Python, Java-free autorouter:

uv tool install freeroute
# or: pip install freeroute

That is the whole setup. freeroute is pure standard library with no dependencies and no Java runtime. mckicad auto-discovers the freeroute command on your PATH; if it lives somewhere unusual, set FREEROUTE_CLI in your .env to the executable path. Verify with the check_routing_capability tool.

See the Autorouting guide for the full pipeline, engine choices, and honest scope.

Fallback: FreeRouting JAR

freeroute completes fewer nets than the original FreeRouting engine on dense commercial boards (it drops a net rather than emit a DRC violation). If you need maximum completion on a hard board and have Java available, keep the FreeRouting JAR as a fallback:

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. Or set FREEROUTING_JAR_PATH in your .env file to an explicit path

mckicad prefers freeroute when it is installed and falls back to the JAR only when freeroute is missing or cannot route the board.

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