Platform Guide: Linux, macOS & Windows

This guide explains the differences between using KiCAD MCP Server on Linux, macOS, and Windows platforms.

Last Updated: 2026-04-11

Quick Comparison

Feature	Linux	Windows	macOS
Primary Support	Full (tested extensively)	Community tested	Community tested
Setup Complexity	Moderate	Easy (automated script)	Easy (automated script)
Prerequisites	Manual package management	Automated detection	Automated detection
KiCAD Python Access	System paths	Bundled with KiCAD	Bundled with KiCAD
Path Separators	Forward slash (/)	Backslash (\) or forward slash	Forward slash (/)
Virtual Environments	Recommended	Optional	Optional
Troubleshooting	Standard Linux tools	PowerShell diagnostics	Bash diagnostics

Installation Differences

Linux Installation

Advantages:

Native package manager integration
Better tested and documented
More predictable Python environments
Standard Unix paths

Process:

Install KiCAD 9.0 via package manager (apt, dnf, pacman)
Install Node.js via package manager or nvm
Clone repository
Install dependencies manually
Build project
Configure MCP client
Set PYTHONPATH environment variable

Typical paths:

KiCAD Python: /usr/lib/kicad/lib/python3/dist-packages
Node.js: /usr/bin/node
Python: /usr/bin/python3

Configuration example:

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

macOS Installation

Advantages:

Automated setup script (setup-macos.sh) handles detection and configuration
KiCAD includes bundled Python (no system Python needed for pcbnew)
Prerequisite checks with clear pass/fail output
Generates and merges Claude Desktop configuration automatically

Process:

Install KiCAD 9.0 from the official .dmg installer
Install Node.js (e.g. via Homebrew or nvm)
Clone repository
Run npm install && npm run build
Run setup-macos.sh:
- bash setup-macos.sh --verify — check prerequisites and detected paths
- bash setup-macos.sh --dry-run — preview the merged Claude Desktop config
- bash setup-macos.sh --apply — write the configuration

Typical paths:

KiCAD Python: /Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3
KiCAD Libraries: /Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/3.x/lib/python3.x/site-packages
Node.js: /usr/local/bin/node  # or via nvm

Configuration example:

{
  "mcpServers": {
    "kicad": {
      "command": "node",
      "args": ["/Users/username/KiCAD-MCP-Server/dist/index.js"],
      "env": {
        "KICAD_PYTHON": "/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3",
        "PYTHONPATH": "/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/3.9/lib/python3.9/site-packages"
      }
    }
  }
}

Windows Installation

Advantages:

Automated setup script handles everything
KiCAD includes bundled Python (no system Python needed)
Better error diagnostics
Comprehensive troubleshooting guide

Process:

Install KiCAD 9.0 from official installer
Install Node.js from official installer
Clone repository
Run setup-windows.ps1 script
- Auto-detects KiCAD installation
- Auto-detects Python paths
- Installs all dependencies
- Builds project
- Generates configuration
- Validates setup

Typical paths:

KiCAD Python: C:\Program Files\KiCad\9.0\bin\python.exe
KiCAD Libraries: C:\Program Files\KiCad\9.0\lib\python3\dist-packages
Node.js: C:\Program Files\nodejs\node.exe

Configuration example:

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

Path Handling

Linux Paths

Use forward slashes: /home/user/project
Case-sensitive filesystem
No drive letters
Symbolic links commonly used

Example commands:

cd /home/username/KiCAD-MCP-Server
export PYTHONPATH=/usr/lib/kicad/lib/python3/dist-packages
python3 -c "import pcbnew"

macOS Paths

Use forward slashes: /Users/username/project
Case-insensitive but case-preserving filesystem (APFS default)
No drive letters
KiCAD paths are inside the .app bundle

Example commands:

cd ~/KiCAD-MCP-Server
export KICAD_PYTHON=/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3
"$KICAD_PYTHON" -c "import pcbnew"

Windows Paths

Use backslashes in native commands: C:\Users\username
Use double backslashes in JSON: C:\\Users\\username
OR use forward slashes in JSON: C:/Users/username
Case-insensitive filesystem (but preserve case)
Drive letters required (C:, D:, etc.)

Example commands:

cd C:\Users\username\KiCAD-MCP-Server
$env:PYTHONPATH = "C:\Program Files\KiCad\9.0\lib\python3\dist-packages"
& "C:\Program Files\KiCad\9.0\bin\python.exe" -c "import pcbnew"

JSON configuration notes:

// Wrong - single backslash will cause errors
"args": ["C:\Users\name\project"]

// Correct - double backslashes
"args": ["C:\\Users\\name\\project"]

// Also correct - forward slashes work in JSON
"args": ["C:/Users/name/project"]

Python Environment

Linux

System Python:

Usually Python 3.10+ available system-wide
KiCAD uses system Python with additional modules
Virtual environments recommended for isolation

Setup:

# Check Python version
python3 --version

# Verify pcbnew module
python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"

# Install project dependencies
pip3 install -r requirements.txt

# Or use virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

PYTHONPATH:

# Temporary (current session)
export PYTHONPATH=/usr/lib/kicad/lib/python3/dist-packages

# Permanent (add to ~/.bashrc or ~/.profile)
echo 'export PYTHONPATH=/usr/lib/kicad/lib/python3/dist-packages' >> ~/.bashrc

macOS

KiCAD Bundled Python:

KiCAD bundles Python inside the .app framework (versions 3.9–3.12)
No system Python installation needed for pcbnew
setup-macos.sh detects the correct path automatically

Setup:

# Check KiCAD Python
/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3 --version

# Verify pcbnew module
/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"

# Or use the setup script to verify everything at once
bash setup-macos.sh --verify

Windows

KiCAD Bundled Python:

KiCAD 9.0 includes Python 3.11
No system Python installation needed
Use KiCAD's Python for all MCP operations

Setup:

# Check KiCAD Python
& "C:\Program Files\KiCad\9.0\bin\python.exe" --version

# Verify pcbnew module
& "C:\Program Files\KiCad\9.0\bin\python.exe" -c "import pcbnew; print(pcbnew.GetBuildVersion())"

# Install project dependencies using KiCAD Python
& "C:\Program Files\KiCad\9.0\bin\python.exe" -m pip install -r requirements.txt

PYTHONPATH:

# Temporary (current session)
$env:PYTHONPATH = "C:\Program Files\KiCad\9.0\lib\python3\dist-packages"

# In MCP configuration (permanent)
{
  "env": {
    "PYTHONPATH": "C:\\Program Files\\KiCad\\9.0\\lib\\python3\\dist-packages"
  }
}

Testing and Debugging

Linux

Check KiCAD installation:

which kicad
kicad --version

Check Python module:

python3 -c "import sys; print(sys.path)"
python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"

Run tests:

cd /home/username/KiCAD-MCP-Server
npm test
pytest tests/

View logs:

tail -f ~/.kicad-mcp/logs/kicad_interface.log

Start server manually:

export PYTHONPATH=/usr/lib/kicad/lib/python3/dist-packages
node dist/index.js

macOS

Check KiCAD installation:

ls /Applications/KiCad/KiCad.app

Run automated diagnostics:

bash setup-macos.sh --verify

View logs:

tail -f ~/.kicad-mcp/logs/kicad_interface.log

Start server manually:

node dist/index.js

Windows

Check KiCAD installation:

Test-Path "C:\Program Files\KiCad\9.0"
& "C:\Program Files\KiCad\9.0\bin\kicad.exe" --version

Check Python module:

& "C:\Program Files\KiCad\9.0\bin\python.exe" -c "import sys; print(sys.path)"
& "C:\Program Files\KiCad\9.0\bin\python.exe" -c "import pcbnew; print(pcbnew.GetBuildVersion())"

Run automated diagnostics:

.\setup-windows.ps1

View logs:

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

Start server manually:

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

Common Issues

Linux-Specific Issues

1. Permission Errors

# Fix file permissions
chmod +x python/kicad_interface.py

# Fix directory permissions
chmod -R 755 ~/KiCAD-MCP-Server

2. PYTHONPATH Not Set

# Check current PYTHONPATH
echo $PYTHONPATH

# Find KiCAD Python path
find /usr -name "pcbnew.py" 2>/dev/null

3. KiCAD Not in PATH

# Add to PATH temporarily
export PATH=$PATH:/usr/bin

# Or use full path to KiCAD
/usr/bin/kicad

4. Library Dependencies

# Install missing system libraries
sudo apt-get install python3-wxgtk4.0 python3-cairo

# Check library linkage
ldd /usr/lib/kicad/lib/python3/dist-packages/pcbnew.so

macOS-Specific Issues

1. KiCad Python Not Found

# Verify the expected path exists
ls /Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3

# If installed elsewhere, set the override
export KICAD_PYTHON=/path/to/your/kicad/python3
bash setup-macos.sh --verify

2. pcbnew Import Fails

Run bash setup-macos.sh --verify — the Prerequisites section will show a ✗ if pcbnew can't be imported
Reinstall KiCAD if the bundled Python is corrupted

3. Claude Config Not Picked Up

Default path is ~/Library/Application Support/Claude/claude_desktop_config.json
Use --claude-config flag to point to a different location
Fully quit and reopen Claude Desktop after changes

Windows-Specific Issues

1. Server Exits Immediately

Most common issue
Usually means pcbnew import failed
Solution: Run setup-windows.ps1 for diagnostics

2. Path Issues in Configuration

# Test path accessibility
Test-Path "C:\Users\name\KiCAD-MCP-Server\dist\index.js"

# Use Tab completion in PowerShell to get correct paths
cd C:\Users\[TAB]

3. PowerShell Execution Policy

# Check current policy
Get-ExecutionPolicy

# Set policy to allow scripts (if needed)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

4. Antivirus Blocking

Windows Defender may block Node.js or Python processes
Solution: Add exclusion for project directory in Windows Security

Performance Considerations

Linux

Generally faster file I/O operations
Better process management
Lower memory overhead
Native Unix socket support (future IPC backend)

Windows

Slightly slower file operations
More memory overhead
Extra startup validation checks (for diagnostics)
Named pipes for IPC (future backend)

Both platforms perform equivalently for normal PCB design operations.

Development Workflow

Linux Development Environment

Typical workflow:

# Start development
cd ~/KiCAD-MCP-Server
code .  # Open in VSCode

# Watch mode for TypeScript
npm run watch

# Run tests in another terminal
npm test

# Test Python changes
python3 python/kicad_interface.py

Recommended tools:

Terminal: GNOME Terminal, Konsole, or Alacritty
Editor: VSCode with Python and TypeScript extensions
Process monitoring: htop or top
Log viewing: tail -f or less +F

Windows Development Environment

Typical workflow:

# Start development
cd C:\Users\username\KiCAD-MCP-Server
code .  # Open in VSCode

# Watch mode for TypeScript
npm run watch

# Run tests in another PowerShell window
npm test

# Test Python changes
& "C:\Program Files\KiCad\9.0\bin\python.exe" python\kicad_interface.py

Recommended tools:

Terminal: Windows Terminal or PowerShell 7
Editor: VSCode with Python and TypeScript extensions
Process monitoring: Task Manager or Process Explorer
Log viewing: Get-Content -Wait or Notepad++

Best Practices

Linux

Use virtual environments for Python dependencies
Set PYTHONPATH in your shell profile for persistence
Use absolute paths in MCP configuration
Check file permissions if encountering access errors
Monitor system logs with journalctl if needed

macOS

Run setup-macos.sh --verify first — confirms all prerequisites
Use --dry-run before --apply — review the merged config before writing
Use KiCAD's bundled Python — don't rely on system or Homebrew Python for pcbnew
Override with KICAD_PYTHON env var if KiCAD is in a non-standard location
Check logs in ~/.kicad-mcp/logs/ when debugging

Windows

Run setup-windows.ps1 first - saves time troubleshooting
Use KiCAD's bundled Python - don't install system Python
Use forward slashes in JSON configs to avoid escaping
Check log file when debugging - it has detailed errors
Keep paths short - avoid deeply nested directories

Migration Between Platforms

Moving from Linux to Windows

Clone repository on Windows machine
Run setup-windows.ps1
Update config file path separators (/ to \)
Update PYTHONPATH to Windows format
No project file changes needed (KiCAD files are cross-platform)

Moving from Windows to Linux

Clone repository on Linux machine
Follow Linux installation steps
Update config file path separators (\ to /)
Update PYTHONPATH to Linux format
Set file permissions: chmod +x python/kicad_interface.py

Moving to/from macOS

Clone repository on the target machine
Run npm install && npm run build
Run bash setup-macos.sh --apply (to macOS) or follow the target platform's setup
No project file changes needed

KiCAD project files (.kicad_pro, .kicad_pcb) are identical across platforms.

Getting Help

Linux Support

Check: README.md Linux installation section
Read: KNOWN_ISSUES.md
Search: GitHub Issues filtered by linux label
Community: Linux users in Discussions

macOS Support

Check: README.md macOS installation section
Run: bash setup-macos.sh --verify for automated diagnostics
Search: GitHub Issues filtered by macos label
Community: macOS users in Discussions

Windows Support

Check: README.md Windows installation section
Read: WINDOWS_TROUBLESHOOTING.md
Run: setup-windows.ps1 for automated diagnostics
Search: GitHub Issues filtered by windows label
Community: Windows users in Discussions

Summary

Choose Linux if:

You're comfortable with command-line tools
You want the most stable, tested environment
You're developing or contributing to the project
You need maximum performance

Choose macOS if:

You're already using KiCAD on macOS
You want automated setup with setup-macos.sh
You prefer a Unix-based development environment

Choose Windows if:

You want automated setup and diagnostics
You're less comfortable with terminal commands
You need detailed troubleshooting guidance
You're a KiCAD user new to development tools

All platforms work well for PCB design with KiCAD MCP. Choose based on your comfort level and existing development environment.

For platform-specific installation instructions, see:

Linux: README.md - Linux Installation
macOS: README.md - macOS Installation
Windows: README.md - Windows Installation

For troubleshooting:

Linux: KNOWN_ISSUES.md
macOS: Run bash setup-macos.sh --verify
Windows: WINDOWS_TROUBLESHOOTING.md

FilesExpand file tree

PLATFORM_GUIDE.md

Latest commit

History

PLATFORM_GUIDE.md

File metadata and controls

Platform Guide: Linux, macOS & Windows

Quick Comparison

Installation Differences

Linux Installation

macOS Installation

Windows Installation

Path Handling

Linux Paths

macOS Paths

Windows Paths

Python Environment

Linux

macOS

Windows

Testing and Debugging

Linux

macOS

Windows

Common Issues

Linux-Specific Issues

macOS-Specific Issues

Windows-Specific Issues

Performance Considerations

Linux

Windows

Development Workflow

Linux Development Environment

Windows Development Environment

Best Practices

Linux

macOS

Windows

Migration Between Platforms

Moving from Linux to Windows

Moving from Windows to Linux

Moving to/from macOS

Getting Help

Linux Support

macOS Support

Windows Support

Summary