KiCAD-MCP-Server/docs/CLIENT_CONFIGURATION.md

KiCAD MCP Server - Client Configuration Guide

This guide shows how to configure the KiCAD MCP Server with various MCP-compatible clients.

---

Quick Reference

Client	Config File Location
Claude Desktop	Linux: ~/.config/Claude/claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json
Cline (VSCode)	VSCode Settings → Extensions → Cline → MCP Settings
Claude Code	~/.config/claude-code/mcp_config.json

---

1. Claude Desktop

Linux Configuration

File: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "kicad": {
      "command": "node",
      "args": ["/home/YOUR_USERNAME/MCP/KiCAD-MCP-Server/dist/index.js"],
      "env": {
        "PYTHONPATH": "/usr/lib/kicad/lib/python3/dist-packages",
        "NODE_ENV": "production"
      }
    }
  }
}

Important: Replace /home/YOUR_USERNAME with your actual home directory path.

macOS Configuration

File: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "kicad": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/MCP/KiCAD-MCP-Server/dist/index.js"]
    }
  }
}

Note: For standard KiCad installations in /Applications/KiCad/, the server auto-detects KiCad's bundled Python (versions 3.9-3.12). No PYTHONPATH configuration is required.

If KiCad is installed in a non-standard location, you can override the Python path:

{
  "mcpServers": {
    "kicad": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/MCP/KiCAD-MCP-Server/dist/index.js"],
      "env": {
        "KICAD_PYTHON": "/custom/path/to/python3"
      }
    }
  }
}

Windows Configuration

File: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "kicad": {
      "command": "node",
      "args": ["C:\\Users\\YOUR_USERNAME\\MCP\\KiCAD-MCP-Server\\dist\\index.js"],
      "env": {
        "PYTHONPATH": "C:\\Program Files\\KiCad\\9.0\\bin\\Lib\\site-packages",
        "NODE_ENV": "production"
      }
    }
  }
}

Note: Use double backslashes (\\) in Windows paths.

---

2. Cline (VSCode Extension)

Configuration Steps

1. Open VSCode
2. Install Cline extension from marketplace
3. Open Settings (Ctrl+,)
4. Search for "Cline MCP"
5. Click "Edit in settings.json"

settings.json Configuration

{
  "cline.mcpServers": {
    "kicad": {
      "command": "node",
      "args": ["/home/YOUR_USERNAME/MCP/KiCAD-MCP-Server/dist/index.js"],
      "env": {
        "PYTHONPATH": "/usr/lib/kicad/lib/python3/dist-packages"
      }
    }
  }
}

Alternative: Workspace Configuration

Create .vscode/settings.json in your project:

{
  "cline.mcpServers": {
    "kicad": {
      "command": "node",
      "args": ["${workspaceFolder}/../KiCAD-MCP-Server/dist/index.js"],
      "env": {
        "PYTHONPATH": "/usr/lib/kicad/lib/python3/dist-packages"
      }
    }
  }
}

---

3. Claude Code CLI

Configuration File

File: ~/.config/claude-code/mcp_config.json

{
  "mcpServers": {
    "kicad": {
      "command": "node",
      "args": ["/home/YOUR_USERNAME/MCP/KiCAD-MCP-Server/dist/index.js"],
      "env": {
        "PYTHONPATH": "/usr/lib/kicad/lib/python3/dist-packages",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Verify Configuration

# List available MCP servers
claude-code mcp list

# Test KiCAD server connection
claude-code mcp test kicad

---

4. Generic MCP Client

For any MCP-compatible client that supports STDIO transport:

Basic Configuration

{
  "command": "node",
  "args": ["/path/to/KiCAD-MCP-Server/dist/index.js"],
  "transport": "stdio",
  "env": {
    "PYTHONPATH": "/path/to/kicad/python/packages"
  }
}

With Custom Config File

{
  "command": "node",
  "args": [
    "/path/to/KiCAD-MCP-Server/dist/index.js",
    "--config",
    "/path/to/custom-config.json"
  ],
  "transport": "stdio"
}

---

Environment Variables

Required

Variable	Description	Example
PYTHONPATH	Path to KiCAD Python modules	/usr/lib/kicad/lib/python3/dist-packages

Optional

Variable	Description	Default
LOG_LEVEL	Logging verbosity	info
NODE_ENV	Node environment	development
KICAD_BACKEND	Force backend (swig or ipc)	Auto-detect

---

Finding KiCAD Python Path

Linux (Ubuntu/Debian)

# Method 1: dpkg query
dpkg -L kicad | grep "site-packages" | head -1

# Method 2: Python auto-detect
python3 -c "from pathlib import Path; import sys; print([p for p in Path('/usr').rglob('pcbnew.py')])"

# Method 3: Use platform helper
cd /path/to/KiCAD-MCP-Server
PYTHONPATH=python python3 -c "from utils.platform_helper import PlatformHelper; print(PlatformHelper.get_kicad_python_paths())"

macOS

# Typical location
/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/lib/python3.11/site-packages

# Find dynamically
find /Applications/KiCad -name "pcbnew.py" -type f

Windows

REM Typical location (KiCAD 9.0)
C:\Program Files\KiCad\9.0\bin\Lib\site-packages

REM Search for pcbnew.py
where /r "C:\Program Files\KiCad" pcbnew.py

---

Testing Your Configuration

1. Verify Server Starts

# Start server manually
node dist/index.js

# Should see output like:
# [INFO] Using STDIO transport for local communication
# [INFO] Registering KiCAD tools, resources, and prompts...
# [INFO] Successfully connected to STDIO transport

Press Ctrl+C to stop.

2. Test with Claude Desktop

1. Restart Claude Desktop
2. Start a new conversation
3. Look for a "hammer" icon or "Tools" indicator
4. The KiCAD tools should be listed

3. Test with Cline

1. Open Cline panel in VSCode
2. Start a new chat
3. Type: "List available KiCAD tools"
4. Cline should show KiCAD MCP tools are available

4. Test with Claude Code

# Start Claude Code with MCP
claude-code

# In the conversation, ask:
# "What KiCAD tools are available?"

---

Troubleshooting

Server Not Starting

Error: Cannot find module 'pcbnew'

Solution: Verify PYTHONPATH is correct:

python3 -c "import sys; sys.path.append('/usr/lib/kicad/lib/python3/dist-packages'); import pcbnew; print(pcbnew.GetBuildVersion())"

Error: ENOENT: no such file or directory

Solution: Check that dist/index.js exists:

cd /path/to/KiCAD-MCP-Server
npm run build
ls -lh dist/index.js

Client Can't Connect

Issue: Claude Desktop doesn't show KiCAD tools

Solutions:

1. Restart Claude Desktop completely (quit, not just close window)
2. Check config file syntax with jq:

   jq . ~/.config/Claude/claude_desktop_config.json
   

3. Check Claude Desktop logs:
   • Linux: ~/.config/Claude/logs/
   • macOS: ~/Library/Logs/Claude/
   • Windows: %APPDATA%\Claude\logs\

Python Module Errors

Error: ModuleNotFoundError: No module named 'kicad_api'

Solution: Server is looking for the wrong Python modules. This is an internal error. Check:

# Verify PYTHONPATH in server config includes both KiCAD and our modules
"PYTHONPATH": "/usr/lib/kicad/lib/python3/dist-packages:/path/to/KiCAD-MCP-Server/python"

---

Advanced Configuration

Multiple KiCAD Versions

If you have multiple KiCAD versions installed:

{
  "mcpServers": {
    "kicad-9": {
      "command": "node",
      "args": ["/path/to/KiCAD-MCP-Server/dist/index.js"],
      "env": {
        "PYTHONPATH": "/usr/lib/kicad-9/lib/python3/dist-packages"
      }
    },
    "kicad-8": {
      "command": "node",
      "args": ["/path/to/KiCAD-MCP-Server/dist/index.js"],
      "env": {
        "PYTHONPATH": "/usr/lib/kicad-8/lib/python3/dist-packages"
      }
    }
  }
}

Custom Logging

Create a custom config file config/production.json:

{
  "logLevel": "debug",
  "python": {
    "executable": "python3",
    "timeout": 30000
  }
}

Then use it:

{
  "command": "node",
  "args": [
    "/path/to/dist/index.js",
    "--config",
    "/path/to/config/production.json"
  ]
}

Development vs Production

Development (verbose logging):

{
  "env": {
    "NODE_ENV": "development",
    "LOG_LEVEL": "debug"
  }
}

Production (minimal logging):

{
  "env": {
    "NODE_ENV": "production",
    "LOG_LEVEL": "info"
  }
}

---

Platform-Specific Examples

Ubuntu 24.04 LTS

{
  "mcpServers": {
    "kicad": {
      "command": "node",
      "args": ["/home/chris/MCP/KiCAD-MCP-Server/dist/index.js"],
      "env": {
        "PYTHONPATH": "/usr/share/kicad/scripting/plugins:/usr/lib/kicad/lib/python3/dist-packages"
      }
    }
  }
}

Arch Linux

{
  "mcpServers": {
    "kicad": {
      "command": "node",
      "args": ["/home/user/KiCAD-MCP-Server/dist/index.js"],
      "env": {
        "PYTHONPATH": "/usr/lib/python3.12/site-packages"
      }
    }
  }
}

Windows 11 with WSL2

Running server in WSL2, client on Windows:

{
  "mcpServers": {
    "kicad": {
      "command": "wsl",
      "args": [
        "node",
        "/home/user/KiCAD-MCP-Server/dist/index.js"
      ],
      "env": {
        "PYTHONPATH": "/usr/lib/kicad/lib/python3/dist-packages"
      }
    }
  }
}

---

Security Considerations

File Permissions

Ensure config files are only readable by your user:

chmod 600 ~/.config/Claude/claude_desktop_config.json

Network Isolation

The KiCAD MCP Server uses STDIO transport (no network ports), providing isolation by default.

Code Execution

The server executes Python scripts from the python/ directory. Only run servers from trusted sources.

---

Next Steps

After configuration:

1. Test Basic Functionality

   • Ask: "Create a new KiCAD project called 'test'"
   • Ask: "What tools are available for PCB design?"

2. Explore Resources

   • Ask: "Show me board information"
   • Ask: "What layers are in my PCB?"

3. Try Advanced Features

   • Ask: "Add a resistor to my schematic"
   • Ask: "Route a trace between two points"

---

Support

If you encounter issues:

1. Check logs in ~/.kicad-mcp/logs/ (if logging is enabled)
2. Verify KiCAD installation: kicad-cli version
3. Test Python modules: python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"
4. Review server startup logs (manual start with node dist/index.js)
5. Check client-specific logs (see Troubleshooting section)

For bugs or feature requests, open an issue on GitHub.

---

Last Updated: October 25, 2025 Version: 2.0.0-alpha.1