kicad-mcp-server/docs/WINDOWS_TROUBLESHOOTING.md

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

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

1. **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.

2. **Test pcbnew import manually:**
   ```powershell
   & "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

3. **Verify PYTHONPATH in your config:**
   ```json
   {
     "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:**

1. **Check if KiCAD is installed:**
   ```powershell
   Test-Path "C:\Program Files\KiCad\9.0"
   ```

2. **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"
     ```

3. **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:**

1. **Check if Node.js is installed:**
   ```powershell
   node --version
   npm --version
   ```

2. **If not installed:**
   - Download Node.js 18+ from https://nodejs.org/
   - Install with default options
   - Restart PowerShell after installation

3. **If installed but not in PATH:**
   ```powershell
   # 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:**

1. **Clean and reinstall dependencies:**
   ```powershell
   Remove-Item node_modules -Recurse -Force
   Remove-Item package-lock.json -Force
   npm install
   npm run build
   ```

2. **Check Node.js version:**
   ```powershell
   node --version  # Should be v18.0.0 or higher
   ```

3. **If still failing:**
   ```powershell
   # 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:**

1. **Install with KiCAD's Python:**
   ```powershell
   & "C:\Program Files\KiCad\9.0\bin\python.exe" -m pip install -r requirements.txt
   ```

2. **If pip is not available:**
   ```powershell
   # 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:**

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

2. **Or clone to user directory:**
   ```powershell
   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:**
```json
// ❌ 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:**
```json
{
  "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`

```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`

```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:

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

```powershell
& "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

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

### Test 3: Build Project

```powershell
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

```powershell
$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

```powershell
# 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:
```json
{
  "env": {
    "LOG_LEVEL": "debug",
    "PYTHONUNBUFFERED": "1"
  }
}
```

### Check Python sys.path

```powershell
& "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

```powershell
# 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:

1. **Run the diagnostic script:**
   ```powershell
   .\setup-windows.ps1
   ```
   Copy the entire output.

2. **Collect log files:**
   - MCP log: `%USERPROFILE%\.kicad-mcp\logs\kicad_interface.log`
   - Claude Desktop log: `%APPDATA%\Claude\logs\mcp*.log`

3. **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

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

2. **Long path support** may be needed for deeply nested projects:
   ```powershell
   # Enable long paths (requires admin)
   New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
   ```

3. **Windows Defender** may slow down file operations. Add exclusion:
   ```
   Settings → Windows Security → Virus & threat protection → Exclusions
   Add: C:\Users\YourName\KiCAD-MCP-Server
   ```

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

---

## Success Checklist

When everything works, you should have:

- [ ] KiCAD 9.0+ installed at `C:\Program Files\KiCad\9.0`
- [ ] Node.js 18+ installed and in PATH
- [ ] Python can import pcbnew successfully
- [ ] `npm run build` completes without errors
- [ ] `dist\index.js` file exists
- [ ] MCP config file created with correct paths
- [ ] Server starts without immediate crash
- [ ] Log file shows successful initialization
- [ ] Claude Desktop/Cline recognizes the MCP server
- [ ] Can execute: "Create a new KiCAD project"

---

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

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