Windows Troubleshooting Guide

This guide helps diagnose and fix common issues when setting up KiCAD MCP Server on Windows.

Quick Start: Automated Setup

Before manually troubleshooting, try the automated setup script:

# Open PowerShell in the KiCAD-MCP-Server directory
.\setup-windows.ps1

This script will:

Detect your KiCAD installation
Verify all prerequisites
Install dependencies
Build the project
Generate configuration
Run diagnostic tests

If the automated setup fails, continue with the manual troubleshooting below.

Common Issues and Solutions

Issue 1: Server Exits Immediately (Most Common)

Symptom: Claude Desktop logs show "Server transport closed unexpectedly"

Cause: Python process crashes during startup, usually due to missing pcbnew module

Solution:

Check the log file (this has the actual error):
```
%USERPROFILE%\.kicad-mcp\logs\kicad_interface.log
```
Open in Notepad and look at the last 50-100 lines.
Test pcbnew import manually:
```
& "C:\Program Files\KiCad\9.0\bin\python.exe" -c "import pcbnew; print(pcbnew.GetBuildVersion())"
```
Expected: Prints KiCAD version like 9.0.0

If it fails:
- KiCAD's Python module isn't installed
- Reinstall KiCAD with default options
- Make sure "Install Python" is checked during installation

Verify PYTHONPATH in your config:

{
  "mcpServers": {
    "kicad": {
      "env": {
        "PYTHONPATH": "C:\\Program Files\\KiCad\\9.0\\lib\\python3\\dist-packages"
      }
    }
  }
}

Issue 2: KiCAD Not Found

Symptom: Log shows "No KiCAD installations found"

Solution:

Check if KiCAD is installed:
```
Test-Path "C:\Program Files\KiCad\9.0"
```
If KiCAD is installed elsewhere:
- Find your KiCAD installation directory
- Update PYTHONPATH in config to match your installation
- Example for version 8.0:
```
"PYTHONPATH": "C:\\Program Files\\KiCad\\8.0\\lib\\python3\\dist-packages"
```
If KiCAD is not installed:
- Download from https://www.kicad.org/download/windows/
- Install version 9.0 or higher
- Use default installation path

Issue 3: Node.js Not Found

Symptom: Cannot run npm install or npm run build

Solution:

Check if Node.js is installed:
```
node --version
npm --version
```
If not installed:
- Download Node.js 18+ from https://nodejs.org/
- Install with default options
- Restart PowerShell after installation

If installed but not in PATH:

# Add to PATH temporarily
$env:PATH += ";C:\Program Files\nodejs"

Issue 4: Build Fails with TypeScript Errors

Symptom: npm run build shows TypeScript compilation errors

Solution:

Clean and reinstall dependencies:

Remove-Item node_modules -Recurse -Force
Remove-Item package-lock.json -Force
npm install
npm run build

Check Node.js version:

node --version  # Should be v18.0.0 or higher

If still failing:

# Try with legacy peer deps
npm install --legacy-peer-deps
npm run build

Issue 5: Python Dependencies Missing

Symptom: Log shows errors about missing Python packages (Pillow, cairosvg, etc.)

Solution:

Install with KiCAD's Python:

& "C:\Program Files\KiCad\9.0\bin\python.exe" -m pip install -r requirements.txt

If pip is not available:

# Download get-pip.py
Invoke-WebRequest -Uri https://bootstrap.pypa.io/get-pip.py -OutFile get-pip.py

# Install pip
& "C:\Program Files\KiCad\9.0\bin\python.exe" get-pip.py

# Then install requirements
& "C:\Program Files\KiCad\9.0\bin\python.exe" -m pip install -r requirements.txt

Issue 6: Permission Denied Errors

Symptom: Cannot write to Program Files or access certain directories

Solution:

Run PowerShell as Administrator:
- Right-click PowerShell icon
- Select "Run as Administrator"
- Navigate to KiCAD-MCP-Server directory
- Run setup again

Or clone to user directory:

cd $HOME\Documents
git clone https://github.com/mixelpixx/KiCAD-MCP-Server.git
cd KiCAD-MCP-Server
.\setup-windows.ps1

Issue 7: Path Issues in Configuration

Symptom: Config file paths not working

Common mistakes:

// ❌ Wrong - single backslashes
"args": ["C:\Users\Name\KiCAD-MCP-Server\dist\index.js"]

// ❌ Wrong - mixed slashes
"args": ["C:\Users/Name\KiCAD-MCP-Server/dist\index.js"]

// ✅ Correct - double backslashes
"args": ["C:\\Users\\Name\\KiCAD-MCP-Server\\dist\\index.js"]

// ✅ Also correct - forward slashes
"args": ["C:/Users/Name/KiCAD-MCP-Server/dist/index.js"]

Solution: Use either double backslashes \\ or forward slashes / consistently.

Issue 8: Wrong Python Version

Symptom: Errors about Python 2.7 or Python 3.6

Solution:

KiCAD MCP requires Python 3.10+. KiCAD 9.0 includes Python 3.11, which is perfect.

Always use KiCAD's bundled Python:

{
  "mcpServers": {
    "kicad": {
      "command": "C:\\Program Files\\KiCad\\9.0\\bin\\python.exe",
      "args": ["C:\\Users\\YourName\\KiCAD-MCP-Server\\python\\kicad_interface.py"]
    }
  }
}

This bypasses Node.js and runs Python directly.

Configuration Examples

For Claude Desktop

Config location: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "kicad": {
      "command": "node",
      "args": ["C:\\Users\\YourName\\KiCAD-MCP-Server\\dist\\index.js"],
      "env": {
        "PYTHONPATH": "C:\\Program Files\\KiCad\\9.0\\lib\\python3\\dist-packages",
        "NODE_ENV": "production",
        "LOG_LEVEL": "info"
      }
    }
  }
}

For Cline (VSCode)

Config location: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

{
  "mcpServers": {
    "kicad": {
      "command": "node",
      "args": ["C:\\Users\\YourName\\KiCAD-MCP-Server\\dist\\index.js"],
      "env": {
        "PYTHONPATH": "C:\\Program Files\\KiCad\\9.0\\lib\\python3\\dist-packages"
      },
      "description": "KiCAD PCB Design Assistant"
    }
  }
}

Alternative: Python Direct Mode

If Node.js issues persist, run Python directly:

{
  "mcpServers": {
    "kicad": {
      "command": "C:\\Program Files\\KiCad\\9.0\\bin\\python.exe",
      "args": ["C:\\Users\\YourName\\KiCAD-MCP-Server\\python\\kicad_interface.py"],
      "env": {
        "PYTHONPATH": "C:\\Program Files\\KiCad\\9.0\\lib\\python3\\dist-packages"
      }
    }
  }
}

Manual Testing Steps

Test 1: Verify KiCAD Python

& "C:\Program Files\KiCad\9.0\bin\python.exe" -c @"
import sys
print(f'Python version: {sys.version}')
import pcbnew
print(f'pcbnew version: {pcbnew.GetBuildVersion()}')
print('SUCCESS!')
"@

Expected output:

Python version: 3.11.x ...
pcbnew version: 9.0.0
SUCCESS!

Test 2: Verify Node.js

node --version  # Should be v18.0.0+
npm --version   # Should be 9.0.0+

Test 3: Build Project

cd C:\Users\YourName\KiCAD-MCP-Server
npm install
npm run build
Test-Path .\dist\index.js  # Should output: True

Test 4: Run Server Manually

$env:PYTHONPATH = "C:\Program Files\KiCad\9.0\lib\python3\dist-packages"
node .\dist\index.js

Expected: Server should start and wait for input (doesn't exit immediately)

To stop: Press Ctrl+C

Test 5: Check Log File

# View log file
Get-Content "$env:USERPROFILE\.kicad-mcp\logs\kicad_interface.log" -Tail 50

Should show successful initialization with no errors.

Advanced Diagnostics

Enable Verbose Logging

Add to your MCP config:

{
  "env": {
    "LOG_LEVEL": "debug",
    "PYTHONUNBUFFERED": "1"
  }
}

Check Python sys.path

& "C:\Program Files\KiCad\9.0\bin\python.exe" -c @"
import sys
for path in sys.path:
    print(path)
"@

Should include: C:\Program Files\KiCad\9.0\lib\python3\dist-packages

Test MCP Communication

# Start server
$env:PYTHONPATH = "C:\Program Files\KiCad\9.0\lib\python3\dist-packages"
$process = Start-Process -FilePath "node" -ArgumentList ".\dist\index.js" -NoNewWindow -PassThru

# Wait 3 seconds
Start-Sleep -Seconds 3

# Check if still running
if ($process.HasExited) {
    Write-Host "Server crashed!" -ForegroundColor Red
    Write-Host "Exit code: $($process.ExitCode)"
} else {
    Write-Host "Server is running!" -ForegroundColor Green
    Stop-Process -Id $process.Id
}

Getting Help

If none of the above solutions work:

Run the diagnostic script:
```
.\setup-windows.ps1
```
Copy the entire output.
Collect log files:
- MCP log: %USERPROFILE%\.kicad-mcp\logs\kicad_interface.log
- Claude Desktop log: %APPDATA%\Claude\logs\mcp*.log
Open a GitHub issue:
- Go to: https://github.com/mixelpixx/KiCAD-MCP-Server/issues
- Title: "Windows Setup Issue: [brief description]"
- Include:
  - Windows version (10 or 11)
  - Output from setup script
  - Log file contents
  - Output from manual tests above

Known Limitations on Windows

File paths are case-insensitive but should match actual casing for best results

Long path support may be needed for deeply nested projects:

# Enable long paths (requires admin)
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Windows Defender may slow down file operations. Add exclusion:

Settings → Windows Security → Virus & threat protection → Exclusions
Add: C:\Users\YourName\KiCAD-MCP-Server

Antivirus software may block Python/Node processes. Temporarily disable for testing.

Success Checklist

When everything works, you should have:

Last Updated: 2025-11-05 Maintained by: KiCAD MCP Team

For the latest updates, see: https://github.com/mixelpixx/KiCAD-MCP-Server

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Windows Troubleshooting Guide

Quick Start: Automated Setup

Common Issues and Solutions

Issue 1: Server Exits Immediately (Most Common)

Issue 2: KiCAD Not Found

Issue 3: Node.js Not Found

Issue 4: Build Fails with TypeScript Errors

Issue 5: Python Dependencies Missing

Issue 6: Permission Denied Errors

Issue 7: Path Issues in Configuration

Issue 8: Wrong Python Version

Configuration Examples

For Claude Desktop

For Cline (VSCode)

Alternative: Python Direct Mode

Manual Testing Steps

Test 1: Verify KiCAD Python

Test 2: Verify Node.js

Test 3: Build Project

Test 4: Run Server Manually

Test 5: Check Log File

Advanced Diagnostics

Enable Verbose Logging

Check Python sys.path

Test MCP Communication

Getting Help

Known Limitations on Windows

Success Checklist

FilesExpand file tree

WINDOWS_TROUBLESHOOTING.md

Latest commit

History

WINDOWS_TROUBLESHOOTING.md

File metadata and controls

Windows Troubleshooting Guide

Quick Start: Automated Setup

Common Issues and Solutions

Issue 1: Server Exits Immediately (Most Common)

Issue 2: KiCAD Not Found

Issue 3: Node.js Not Found

Issue 4: Build Fails with TypeScript Errors

Issue 5: Python Dependencies Missing

Issue 6: Permission Denied Errors

Issue 7: Path Issues in Configuration

Issue 8: Wrong Python Version

Configuration Examples

For Claude Desktop

For Cline (VSCode)

Alternative: Python Direct Mode

Manual Testing Steps

Test 1: Verify KiCAD Python

Test 2: Verify Node.js

Test 3: Build Project

Test 4: Run Server Manually

Test 5: Check Log File

Advanced Diagnostics

Enable Verbose Logging

Check Python sys.path

Test MCP Communication

Getting Help

Known Limitations on Windows

Success Checklist