kicad-mcp/docs-site/src/content/docs/getting-started/configuration.md

title	description
Configuration	Configure mckicad for your environment

Configuration methods

mckicad can be configured through:

1. .env file in the project root (recommended)
2. Environment variables set directly or via your MCP client config
3. Code constants in config.py for static values like file extensions

Core configuration

Project paths

These settings control where the server looks for KiCad projects:

Environment Variable	Description	Default	Example
KICAD_USER_DIR	KiCad user directory	~/Documents/KiCad (macOS/Windows), ~/kicad (Linux)	~/Documents/KiCadProjects
KICAD_SEARCH_PATHS	Additional project directories (comma-separated)	None	~/pcb,~/Electronics,~/Projects/KiCad

Application paths

Environment Variable	Description	Default	Example
KICAD_APP_PATH	Path to the KiCad installation	Auto-detected per platform	/Applications/KiCad/KiCad.app
KICAD_CLI_PATH	Explicit path to kicad-cli	Auto-detected	/usr/bin/kicad-cli
FREEROUTING_JAR_PATH	Path to FreeRouting JAR	Auto-detected in common locations	~/freerouting.jar

Server settings

Environment Variable	Description	Default	Example
LOG_LEVEL	Logging level	INFO	DEBUG

Using a .env file

The recommended approach. Copy the example and edit:

cp .env.example .env

Example .env:

# KiCad user directory
KICAD_USER_DIR=~/Documents/KiCad

# Additional project directories (comma-separated)
KICAD_SEARCH_PATHS=~/pcb,~/Electronics,~/Projects/KiCad

# KiCad application path
# macOS:
KICAD_APP_PATH=/Applications/KiCad/KiCad.app
# Linux:
# KICAD_APP_PATH=/usr/share/kicad
# Windows:
# KICAD_APP_PATH=C:\Program Files\KiCad

The .env file is loaded by main.py before any mckicad imports, which means all config functions see the correct values at runtime.

Project discovery

The server automatically searches for KiCad projects in:

1. The KiCad user directory (KICAD_USER_DIR)
2. Any additional search paths from KICAD_SEARCH_PATHS
3. Common project locations that are auto-detected (e.g., ~/Documents/PCB, ~/Electronics)

Projects are identified by the .kicad_pro file extension. The server searches recursively through all configured directories.

Client configuration

Claude Desktop

Create or edit the configuration file:

macOS:

mkdir -p ~/Library/Application\ Support/Claude

Edit ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: Edit %APPDATA%\Claude\claude_desktop_config.json

Add the server entry:

{
    "mcpServers": {
        "kicad": {
            "command": "/ABSOLUTE/PATH/TO/kicad-mcp/.venv/bin/python",
            "args": [
                "/ABSOLUTE/PATH/TO/kicad-mcp/main.py"
            ]
        }
    }
}

For Windows, use the appropriate path format:

{
    "mcpServers": {
        "kicad": {
            "command": "C:\\Path\\To\\kicad-mcp\\.venv\\Scripts\\python.exe",
            "args": [
                "C:\\Path\\To\\kicad-mcp\\main.py"
            ]
        }
    }
}

Passing environment variables via 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": "/custom/path1,/custom/path2",
                "KICAD_APP_PATH": "/custom/path"
            }
        }
    }
}

Advanced configuration

Custom KiCad extensions

The recognized file extensions are defined in config.py:

KICAD_EXTENSIONS = {
    "project": ".kicad_pro",
    "pcb": ".kicad_pcb",
    "schematic": ".kicad_sch",
}

DRC history

DRC results are stored in:

• macOS/Linux: ~/.mckicad/drc_history/
• Windows: %APPDATA%\mckicad\drc_history\

Platform-specific notes

macOS

KiCad is typically at /Applications/KiCad/KiCad.app. For non-standard installations:

KICAD_APP_PATH=/path/to/your/KiCad.app

Windows

KiCad is typically at C:\Program Files\KiCad. In .env files, use either forward slashes or escaped backslashes:

KICAD_SEARCH_PATHS=C:/Users/Username/Documents/KiCad
KICAD_SEARCH_PATHS=C:\\Users\\Username\\Documents\\KiCad

Linux

KiCad locations vary by distribution. Common paths:

• /usr/share/kicad
• /usr/local/share/kicad
• /opt/kicad

Debugging configuration issues

1. Start the server and check logs:

   uv run python main.py
   

   Logs go to mckicad.log in the project root.

2. Verify environment variables are loaded:

   python -c "import os; print(os.environ.get('KICAD_SEARCH_PATHS', 'Not set'))"
   

3. Use absolute paths to eliminate path resolution issues.

4. Use the MCP Inspector for direct server testing:

   npx @modelcontextprotocol/inspector uv --directory . run main.py