nearxos/kicad-mcp-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add macOS automated setup script and update platform documentation

Browse Source 
Add setup-macos.sh, a shell script that automates Claude Desktop MCP
configuration on macOS. The script detects KiCad's bundled Python,
resolves PYTHONPATH, generates the correct MCP server config, and
safely merges it into the existing Claude Desktop configuration with
backup support. Supports --verify, --dry-run, and --apply modes.

Update README.md with documentation for the automated setup workflow,
including usage examples, parameter reference, and post-setup steps.

Extend docs/PLATFORM_GUIDE.md with macOS-specific sections covering
installation, path handling, Python environment, troubleshooting,
best practices, cross-platform migration, and support resources.

Update docs/STATUS_SUMMARY.md to reflect the new macOS automation
capabilities and bump the last-updated date.
This commit is contained in:
nhebling
2026-04-11 17:25:01 +02:00
parent 227433716a
commit 0255064648
4 changed files with 628 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

187
docs/PLATFORM_GUIDE.md
View File

@@ -1,22 +1,22 @@
# Platform Guide: Linux vs Windows
# Platform Guide: Linux, macOS & Windows
This guide explains the differences between using KiCAD MCP Server on Linux and Windows platforms.
This guide explains the differences between using KiCAD MCP Server on Linux, macOS, and Windows platforms.
**Last Updated:** 2025-11-05
**Last Updated:** 2026-04-11
---
## Quick Comparison
| Feature | Linux | Windows |
| ------------------------ | ------------------------- | ------------------------------- |
| **Primary Support** | Full (tested extensively) | Community tested |
| **Setup Complexity** | Moderate | Easy (automated script) |
| **Prerequisites** | Manual package management | Automated detection |
| **KiCAD Python Access** | System paths | Bundled with KiCAD |
| **Path Separators** | Forward slash (/) | Backslash (\\) or forward slash |
| **Virtual Environments** | Recommended | Optional |
| **Troubleshooting** | Standard Linux tools | PowerShell diagnostics |
| 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 |
---
@@ -65,6 +65,51 @@ Python: /usr/bin/python3
}
```
### 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:**
1. Install KiCAD 9.0 from the official `.dmg` installer
2. Install Node.js (e.g. via Homebrew or nvm)
3. Clone repository
4. Run `npm install && npm run build`
5. 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:**
```bash
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:**
```json
{
"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:**
@@ -130,6 +175,21 @@ 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:**
```bash
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`
@@ -199,6 +259,27 @@ export PYTHONPATH=/usr/lib/kicad/lib/python3/dist-packages
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:**
```bash
# 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:**
@@ -275,6 +356,32 @@ export PYTHONPATH=/usr/lib/kicad/lib/python3/dist-packages
node dist/index.js
```
### macOS
**Check KiCAD installation:**
```bash
ls /Applications/KiCad/KiCad.app
```
**Run automated diagnostics:**
```bash
bash setup-macos.sh --verify
```
**View logs:**
```bash
tail -f ~/.kicad-mcp/logs/kicad_interface.log
```
**Start server manually:**
```bash
node dist/index.js
```
### Windows
**Check KiCAD installation:**
@@ -356,6 +463,30 @@ sudo apt-get install python3-wxgtk4.0 python3-cairo
ldd /usr/lib/kicad/lib/python3/dist-packages/pcbnew.so
```
### macOS-Specific Issues
**1. KiCad Python Not Found**
```bash
# 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 `~/.config/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**
@@ -479,6 +610,14 @@ npm test
4. **Check file permissions** if encountering access errors
5. **Monitor system logs** with `journalctl` if needed
### macOS
1. **Run `setup-macos.sh --verify` first** — confirms all prerequisites
2. **Use `--dry-run` before `--apply`** — review the merged config before writing
3. **Use KiCAD's bundled Python** — don't rely on system or Homebrew Python for pcbnew
4. **Override with `KICAD_PYTHON` env var** if KiCAD is in a non-standard location
5. **Check logs** in `~/.kicad-mcp/logs/` when debugging
### Windows
1. **Run setup-windows.ps1 first** - saves time troubleshooting
@@ -507,6 +646,13 @@ npm test
4. Update PYTHONPATH to Linux format
5. Set file permissions: `chmod +x python/kicad_interface.py`
### Moving to/from macOS
1. Clone repository on the target machine
2. Run `npm install && npm run build`
3. Run `bash setup-macos.sh --apply` (to macOS) or follow the target platform's setup
4. No project file changes needed
**KiCAD project files (.kicad_pro, .kicad_pcb) are identical across platforms.**
---
@@ -520,6 +666,13 @@ npm test
- Search: GitHub Issues filtered by `linux` label
- Community: Linux users in Discussions
### macOS Support
- Check: [README.md](../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](../README.md) Windows installation section
@@ -539,6 +692,12 @@ npm test
- 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
@@ -546,16 +705,18 @@ npm test
- You need detailed troubleshooting guidance
- You're a KiCAD user new to development tools
**Both platforms work well for PCB design with KiCAD MCP. Choose based on your comfort level and existing development environment.**
**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](../README.md#linux-ubuntudebian)
- macOS: [README.md - macOS Installation](../README.md#macos)
- Windows: [README.md - Windows Installation](../README.md#windows-1011)
**For troubleshooting:**
- Linux: [KNOWN_ISSUES.md](./KNOWN_ISSUES.md)
- macOS: Run `bash setup-macos.sh --verify`
- Windows: [WINDOWS_TROUBLESHOOTING.md](./WINDOWS_TROUBLESHOOTING.md)