Skip to content

configuration.md

Latest commit

 

History

History
222 lines (161 loc) · 6.2 KB

configuration.md

File metadata and controls

222 lines (161 loc) · 6.2 KB

Configuration Guide

This guide explains how to configure the KiCad MCP Server to suit your environment and requirements.

Configuration Methods

The KiCad MCP Server can be configured in multiple ways:

  1. Environment Variables: Set directly when running the server
  2. .env File: Create a .env file in the project root (recommended)
  3. Code Modifications: Edit configuration constants in kicad_mcp/config.py

Core Configuration Options

Project Paths

These settings control where the server looks for KiCad projects:

Environment Variable Description Default Value Example
KICAD_USER_DIR The main KiCad user directory ~/Documents/KiCad (macOS/Windows)
~/kicad (Linux)		 ~/Documents/KiCadProjects
KICAD_SEARCH_PATHS Additional directories to search for KiCad projects (comma-separated) None ~/pcb,~/Electronics,~/Projects/KiCad

Application Paths

These settings control how the server locates KiCad:

Environment Variable Description Default Value Example
KICAD_APP_PATH Path to the KiCad application /Applications/KiCad/KiCad.app (macOS)
C:\Program Files\KiCad (Windows)
/usr/share/kicad (Linux)		 /Applications/KiCad7/KiCad.app

Using a .env File (Recommended)

The recommended way to configure the server is by creating a .env file in the project root:

  1. Copy the example file:

    cp .env.example .env

  2. Edit the .env file:

    vim .env

  3. Add your configuration:

    # KiCad MCP Server Configuration

# KiCad User Directory (where KiCad stores project files)
KICAD_USER_DIR=~/Documents/KiCad

# Additional directories to search for KiCad projects (comma-separated)
KICAD_SEARCH_PATHS=~/pcb,~/Electronics,~/Projects/KiCad

# KiCad application path (needed for opening projects and command-line tools)
# macOS:
KICAD_APP_PATH=/Applications/KiCad/KiCad.app
# Windows:
# KICAD_APP_PATH=C:\Program Files\KiCad
# Linux:
# KICAD_APP_PATH=/usr/share/kicad

Directory Structure and Project Discovery

The server automatically searches for KiCad projects in:

  1. The KiCad user directory (KICAD_USER_DIR)
  2. Any additional search paths specified in KICAD_SEARCH_PATHS
  3. Common project locations (auto-detected, including ~/Documents/PCB, ~/Electronics, etc.)

Projects are identified by the .kicad_pro file extension. The server recursively searches all configured directories to find KiCad projects.

Client Configuration

Claude Desktop Configuration

To configure Claude Desktop to use the KiCad MCP Server:

  1. Create or edit the configuration file:

    macOS:

    mkdir -p ~/Library/Application\ Support/Claude
vim ~/Library/Application\ Support/Claude/claude_desktop_config.json

    Windows:

    mkdir -p %APPDATA%\Claude
notepad %APPDATA%\Claude\claude_desktop_config.json

  2. Add the server configuration:

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

  3. For Windows, use the appropriate path format:

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

Environment Variables in Client Configuration

You can also set environment variables directly in the client configuration:

{
    "mcpServers": {
        "kicad": {
            "command": "/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/venv/bin/python",
            "args": [
                "/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/main.py"
            ],
            "env": {
                "KICAD_SEARCH_PATHS": "/custom/path1,/custom/path2",
                "KICAD_APP_PATH": "/custom/path"
            }
        }
    }
}

Advanced Configuration

Custom KiCad Extensions

If you need to modify the recognized KiCad file extensions, you can edit kicad_mcp/config.py:

# File extensions
KICAD_EXTENSIONS = {
    "project": ".kicad_pro",
    "pcb": ".kicad_pcb",
    "schematic": ".kicad_sch",
    # Add or modify extensions as needed
}

DRC History Configuration

The server stores DRC history to track changes over time. By default, history is stored in:

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

You can modify this in kicad_mcp/utils/drc_history.py if needed.

Python Path for KiCad Modules

The server attempts to locate and add KiCad's Python modules to the Python path automatically. If this fails, you can modify the search paths in kicad_mcp/utils/python_path.py.

Platform-Specific Configuration

macOS

On macOS, KiCad is typically installed in /Applications/KiCad/KiCad.app. If you have multiple versions or a non-standard installation, set:

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

Windows

On Windows, KiCad is typically installed in C:\Program Files\KiCad. If you have a different installation location, set:

KICAD_APP_PATH=D:\Software\KiCad

For paths in the .env file on Windows, you can use either:

  • Forward slashes: KICAD_SEARCH_PATHS=C:/Users/Username/Documents/KiCad
  • Escaped backslashes: KICAD_SEARCH_PATHS=C:\\Users\\Username\\Documents\\KiCad

Linux

On Linux, KiCad's location varies by distribution. Common paths include:

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

Set the appropriate path in your configuration:

KICAD_APP_PATH=/opt/kicad

Debugging Configuration Issues

If you're having configuration problems:

  1. Run the server:

    python main.py

  2. Verify environment variables are being loaded:

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

  3. Try absolute paths to eliminate path resolution issues