kicad-mcp/docs/troubleshooting.md

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

     pip install -r requirements.txt
     

2. Python Version

   • Error: Syntax errors or unsupported features
   • Solution: Verify you're using Python 3.10 or higher

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

     cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
     

     For Claude Desktop (Windows):

     type %APPDATA%\Claude\claude_desktop_config.json
     

     Ensure it contains the correct server configuration:

     {
         "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:

     "args": ["main.py"]
     

     With:

     "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

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:

     tail -n 20 -F ~/Library/Logs/Claude/mcp-server-kicad.log
     

   • General MCP logs:

     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:

   python -m mcp.dev main.py
   

2. Use the MCP Inspector for direct server testing:

   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)