KiCad MCP Server

# Troubleshooting Guide This guide helps you troubleshoot common issues with the KiCad MCP Server. ## Server Setup Issues ### Server Not Starting **Symptoms:** - Error messages when running `python main.py` - Server crashes immediately **Possible Causes and Solutions:** 1. **Missing Dependencies** - **Error:** `ModuleNotFoundError: No module named 'mcp'` - **Solution:** Ensure you have installed the required packages ```bash pip install -r requirements.txt ``` 2. **Python Version** - **Error:** Syntax errors or unsupported features - **Solution:** Verify you're using Python 3.10 or higher ```bash python --version ``` 3. **Configuration Issues** - **Error:** `FileNotFoundError` or errors related to paths - **Solution:** Check your `.env` file and ensure all paths exist 4. **Permission Issues** - **Error:** `PermissionError: [Errno 13] Permission denied` - **Solution:** Ensure you have the necessary permissions for all directories and files ## MCP Client Integration Issues ### Server Not Appearing in Client **Symptoms:** - Server not showing in Claude Desktop tools dropdown - Unable to access KiCad tools in the client **Possible Causes and Solutions:** 1. **Configuration File Issues** - **Problem:** Incorrect or missing configuration - **Solution:** Check your client configuration file: For Claude Desktop (macOS): ```bash cat ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` For Claude Desktop (Windows): ```bash type %APPDATA%\Claude\claude_desktop_config.json ``` Ensure it contains the correct server configuration: ```json { "mcpServers": { "kicad": { "command": "/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/venv/bin/python", "args": [ "/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/main.py" ] } } } ``` 2. **Working Directory Issues** - **Problem:** The server can't find files due to working directory issues - **Solution:** Always use absolute paths in your configuration Replace: ```json "args": ["main.py"] ``` With: ```json "args": ["/absolute/path/to/main.py"] ``` 3. **Client Needs Restart** - **Problem:** Changes to configuration not applied - **Solution:** Close and reopen your MCP client 4. **MCP Protocol Version Mismatch** - **Problem:** Client and server using incompatible protocol versions - **Solution:** Update both the client and server to compatible versions ## Working with KiCad ### KiCad Python Modules Not Found **Symptoms:** - Warning messages about missing KiCad Python modules - Limited functionality for PCB analysis, DRC, etc. **Possible Causes and Solutions:** 1. **KiCad Not Installed** - **Problem:** KiCad installation not found - **Solution:** Install KiCad from [kicad.org](https://www.kicad.org/download/) 2. **Non-standard KiCad Installation** - **Problem:** KiCad installed in a non-standard location - **Solution:** Set the `KICAD_APP_PATH` environment variable in your `.env` file: ``` KICAD_APP_PATH=/path/to/KiCad/KiCad.app ``` 3. **Python Path Issues** - **Problem:** KiCad Python modules not in Python path - **Solution:** Check server logs for Python path setup errors ### Unable to Open KiCad Projects **Symptoms:** - Error when trying to open a KiCad project - KiCad doesn't launch when requested **Possible Causes and Solutions:** 1. **KiCad Not Found** - **Problem:** KiCad executable not found - **Solution:** Set the correct `KICAD_APP_PATH` in your `.env` file 2. **Project Path Issues** - **Problem:** Project file not found - **Solution:** Double-check the path to your KiCad project file - Ensure the path is an absolute path - Ensure the file exists and has a `.kicad_pro` extension 3. **Permission Issues** - **Problem:** Insufficient permissions to launch KiCad - **Solution:** Check file and application permissions ## Project Discovery Issues ### KiCad Projects Not Found **Symptoms:** - No projects listed when asking for KiCad projects - Missing specific projects that you know exist **Possible Causes and Solutions:** 1. **Search Path Issues** - **Problem:** Server not looking in the right directories - **Solution:** Configure search paths in your `.env` file: ``` KICAD_SEARCH_PATHS=~/pcb,~/Electronics,~/Projects/KiCad ``` 2. **KiCad User Directory Override** - **Problem:** Custom KiCad user directory not being searched - **Solution:** Set `KICAD_USER_DIR` in your `.env` file: ``` KICAD_USER_DIR=~/Documents/KiCadProjects ``` 3. **File Extension Issues** - **Problem:** Projects not recognized due to file extensions - **Solution:** Ensure your KiCad projects have the `.kicad_pro` extension ## Debugging and Logging ### Checking Logs To diagnose issues, check the server logs: 1. **Development Mode Logs** - When running in development mode with `python -m mcp.dev main.py`, logs appear in the console 2. **Claude Desktop Logs (macOS)** - Server logs: ```bash tail -n 20 -F ~/Library/Logs/Claude/mcp-server-kicad.log ``` - General MCP logs: ```bash tail -n 20 -F ~/Library/Logs/Claude/mcp.log ``` 3. **Claude Desktop Logs (Windows)** - Check logs in: ``` %APPDATA%\Claude\Logs\ ``` ## DRC and Export Feature Issues ### DRC Checks Failing **Symptoms:** - Error messages when running DRC checks - Incomplete DRC results **Possible Causes and Solutions:** 1. **KiCad CLI Tools Not Found** - **Problem:** Command-line tools not available - **Solution:** Ensure you have a complete KiCad installation with CLI tools 2. **PCB File Issues** - **Problem:** Invalid or corrupted PCB file - **Solution:** Verify the PCB file can be opened in KiCad ### PCB Thumbnail Generation Failing **Symptoms:** - Unable to generate PCB thumbnails - Error messages about missing modules **Possible Causes and Solutions:** 1. **Missing KiCad Python Modules** - **Problem:** Unable to import pcbnew module - **Solution:** The server will try alternative methods, but functionality may be limited 2. **File Path Issues** - **Problem:** PCB file not found - **Solution:** Ensure you're using absolute paths and the PCB file exists ## Environment-Specific Issues ### macOS Issues 1. **Permissions** - **Problem:** Permission denied when accessing files - **Solution:** Ensure Terminal has full disk access in System Preferences > Security & Privacy 2. **Python Environment** - **Problem:** System Python vs. Homebrew Python confusion - **Solution:** Specify the full path to the Python interpreter in your client configuration ### Windows Issues 1. **Path Separator Issues** - **Problem:** Backslashes in Windows paths causing issues - **Solution:** Use forward slashes (/) in all paths, or double backslashes (\\\\) 2. **Command Execution** - **Problem:** Issues launching KiCad from the server - **Solution:** Ensure the KICAD_APP_PATH is set correctly in your `.env` file ### Linux Issues 1. **KiCad Installation Location** - **Problem:** KiCad installed in non-standard location - **Solution:** Set KICAD_APP_PATH to your KiCad installation location 2. **Permission Issues** - **Problem:** Unable to access certain files - **Solution:** Check file permissions with `ls -la` and adjust with `chmod` if needed ## Still Having Issues? If you're still experiencing problems: 1. Try running the server in development mode for more detailed output: ```bash python -m mcp.dev main.py ``` 2. Use the MCP Inspector for direct server testing: ```bash npx @modelcontextprotocol/inspector uv --directory . run main.py ``` 3. Open an issue on GitHub with: - A clear description of the problem - Steps to reproduce - Error messages or logs - Your environment details (OS, Python version, KiCad version)