---
title: "Environment Variables"
description: "Complete reference for all mckicad environment variables"
---

All environment variables are read at runtime through lazy config functions in `config.py`. Static constants (file extensions, timeout values, common library names) are module-level and do not read environment variables.

The `.env` file in the project root is loaded by `main.py` before any mckicad imports, ensuring all config functions see the correct values.

## Variable reference

### KICAD_SEARCH_PATHS

Comma-separated list of directories to search for KiCad projects.

```
KICAD_SEARCH_PATHS=~/Documents/KiCad,~/Electronics,~/Projects/KiCad
```

The server searches these directories recursively for `.kicad_pro` files. In addition to these paths, the server checks the KiCad user directory and common auto-detected locations.

**Default:** None (only auto-detected paths are searched)

### KICAD_USER_DIR

The KiCad user documents directory. This is the primary directory searched for projects and is used for various KiCad-related path resolutions.

```
KICAD_USER_DIR=~/Documents/KiCad
```

**Default:**
- macOS/Windows: `~/Documents/KiCad`
- Linux: `~/kicad`

### KICAD_CLI_PATH

Explicit path to the `kicad-cli` executable. Set this if `kicad-cli` is not in your system PATH or is installed in a non-standard location.

```
KICAD_CLI_PATH=/usr/bin/kicad-cli
```

**Default:** Auto-detected from standard installation paths and system PATH

Used by: DRC checks, BOM export, netlist export, Gerber/drill/PDF/SVG export, ERC, autowire netlist extraction.

### KICAD_APP_PATH

Path to the KiCad application installation. Used for opening projects and locating KiCad's bundled tools.

```
KICAD_APP_PATH=/Applications/KiCad/KiCad.app
```

**Default:**
- macOS: `/Applications/KiCad/KiCad.app`
- Windows: `C:\Program Files\KiCad`
- Linux: `/usr/share/kicad`

### FREEROUTE_CLI

Path to the [freeroute](https://pypi.org/project/freeroute/) CLI, the preferred autorouter. freeroute is a native-Python, Java-free port of the FreeRouting engine.

```
FREEROUTE_CLI=~/.local/bin/freeroute
```

**Default:** Auto-discovered on your system PATH. Set this only if the `freeroute` executable is installed in a location that is not on PATH. Install it with `uv tool install freeroute` or `pip install freeroute`.

Used by: `route_pcb_automatically`, `check_routing_capability`.

Per-call engine and packing behaviour is controlled through the `routing_config` argument (`freeroute_engine`, `freeroute_pack`, `freeroute_shove`, `freeroute_diagonal`), not through environment variables. See the [Autorouting guide](/guides/routing/).

### FREEROUTING_JAR_PATH

Path to the FreeRouting JAR file. This is the optional fallback autorouter, used only when freeroute is not installed or cannot route a given board. mckicad prefers freeroute (see `FREEROUTE_CLI`).

```
FREEROUTING_JAR_PATH=~/freerouting.jar
```

**Default:** Auto-detected at these locations:
- `~/freerouting.jar`
- `/usr/local/bin/freerouting.jar`
- `/opt/freerouting/freerouting.jar`

Requires a Java runtime (`java` must be on PATH). Only needed for maximum net completion on dense boards; the primary freeroute path needs no Java.

### LOG_LEVEL

Logging verbosity. Logs are written to `mckicad.log` in the project root, overwritten on each server start.

```
LOG_LEVEL=DEBUG
```

**Default:** `INFO`

**Valid values:** `DEBUG`, `INFO`, `WARNING`, `ERROR`

Never use `print()` in mckicad code -- MCP uses stdin/stdout for JSON-RPC transport, so any print output would corrupt the protocol.

## Example .env file

```bash
# mckicad Configuration

# Project search directories
KICAD_SEARCH_PATHS=~/Documents/KiCad,~/Electronics

# KiCad user directory
KICAD_USER_DIR=~/Documents/KiCad

# Explicit kicad-cli path (if not in PATH)
# KICAD_CLI_PATH=/usr/bin/kicad-cli

# KiCad application path
# KICAD_APP_PATH=/usr/share/kicad

# Autorouter: freeroute is preferred and auto-discovered on PATH.
# Set FREEROUTE_CLI only if it is installed off-PATH.
# FREEROUTE_CLI=~/.local/bin/freeroute

# Optional FreeRouting JAR fallback (needs Java; only for dense boards)
# FREEROUTING_JAR_PATH=~/freerouting.jar

# Logging level
# LOG_LEVEL=INFO
```

## Setting variables via MCP client config

You can pass environment variables directly in the Claude Desktop configuration instead of using a `.env` file:

```json
{
    "mcpServers": {
        "kicad": {
            "command": "/path/to/kicad-mcp/.venv/bin/python",
            "args": ["/path/to/kicad-mcp/main.py"],
            "env": {
                "KICAD_SEARCH_PATHS": "/home/user/Electronics,/home/user/PCB",
                "KICAD_CLI_PATH": "/usr/bin/kicad-cli",
                "LOG_LEVEL": "DEBUG"
            }
        }
    }
}
```

Variables set in the client config take precedence over those in the `.env` file.