kicad-mcp/docs-site/src/content/docs/reference/environment.md

title	description
Environment Variables	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 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.

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

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

{
    "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.