Ryan Malloy
1cb6ad1a59
Some checks failed
CI / Lint and Format (push) Has been cancelled
CI / Test Python 3.11 on macos-latest (push) Has been cancelled
CI / Test Python 3.12 on macos-latest (push) Has been cancelled
CI / Test Python 3.13 on macos-latest (push) Has been cancelled
CI / Test Python 3.10 on ubuntu-latest (push) Has been cancelled
CI / Test Python 3.11 on ubuntu-latest (push) Has been cancelled
CI / Test Python 3.12 on ubuntu-latest (push) Has been cancelled
CI / Test Python 3.13 on ubuntu-latest (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / Build Package (push) Has been cancelled
The docs site is public; the freeroute Gitea repo is private, so link the public PyPI project page instead. Set freeroute_shove/diagonal defaults to false (their actual mckicad routing_config defaults) rather than 'engine-dependent'.
153 lines
4.7 KiB
Markdown
153 lines
4.7 KiB
Markdown
---
|
|
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.
|