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

---
title: "Configuration"
description: "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:

```bash
cp .env.example .env
```

Example `.env`:

```bash
# 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**:
```bash
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:

```json
{
    "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:

```json
{
    "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

```json
{
    "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`:

```python
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:
   ```bash
   uv run python main.py
   ```
   Logs go to `mckicad.log` in the project root.

2. Verify environment variables are loaded:
   ```bash
   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:
   ```bash
   npx @modelcontextprotocol/inspector uv --directory . run main.py
   ```