Update repository with project files and documentation
- Added comprehensive documentation (BUILD_AND_TEST, CLIENT_CONFIG, KNOWN_ISSUES, ROADMAP, etc.) - Updated core functionality for board outline, size, and utilities - Added new tools for project, routing, schematic, and UI management - Included TypeScript SDK with full MCP implementation - Updated configuration examples for all platforms - Added changelog and status tracking - Improved Python utilities with KiCAD process management - Enhanced resource helpers and server capabilities 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
KiCAD MCP Bot
529
docs/CLIENT_CONFIGURATION.md
Normal file
529
docs/CLIENT_CONFIGURATION.md
Normal file
@@ -0,0 +1,529 @@
|
||||
# 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`<br>macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`<br>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`
|
||||
|
||||
```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`
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"kicad": {
|
||||
"command": "node",
|
||||
"args": ["/Users/YOUR_USERNAME/MCP/KiCAD-MCP-Server/dist/index.js"],
|
||||
"env": {
|
||||
"PYTHONPATH": "/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/lib/python3.11/site-packages",
|
||||
"NODE_ENV": "production"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** Adjust Python version (3.11) and KiCAD path based on your installation.
|
||||
|
||||
### Windows Configuration
|
||||
|
||||
**File:** `%APPDATA%\Claude\claude_desktop_config.json`
|
||||
|
||||
```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
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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`
|
||||
|
||||
```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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```json
|
||||
{
|
||||
"command": "node",
|
||||
"args": ["/path/to/KiCAD-MCP-Server/dist/index.js"],
|
||||
"transport": "stdio",
|
||||
"env": {
|
||||
"PYTHONPATH": "/path/to/kicad/python/packages"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### With Custom Config File
|
||||
|
||||
```json
|
||||
{
|
||||
"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)
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```cmd
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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`:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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`:
|
||||
|
||||
```json
|
||||
{
|
||||
"logLevel": "debug",
|
||||
"python": {
|
||||
"executable": "python3",
|
||||
"timeout": 30000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then use it:
|
||||
|
||||
```json
|
||||
{
|
||||
"command": "node",
|
||||
"args": [
|
||||
"/path/to/dist/index.js",
|
||||
"--config",
|
||||
"/path/to/config/production.json"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Development vs Production
|
||||
|
||||
Development (verbose logging):
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"NODE_ENV": "development",
|
||||
"LOG_LEVEL": "debug"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Production (minimal logging):
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"NODE_ENV": "production",
|
||||
"LOG_LEVEL": "info"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Platform-Specific Examples
|
||||
|
||||
### Ubuntu 24.04 LTS
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```bash
|
||||
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
|
||||
Reference in New Issue
Block a user