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

FREEROUTING_JAR_PATH

Path to the FreeRouting JAR file for automated PCB routing.

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).

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

# FreeRouting JAR for autorouting
# 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.