kicad-mcp/docs-site/src/content/docs/development/troubleshooting.md

title	description
Troubleshooting	Common issues and solutions for the mckicad server

Server setup issues

Server not starting

ModuleNotFoundError: No module named 'mcp'

Dependencies are not installed. Run:

make install

Syntax errors or unsupported features

Verify you are using Python 3.10 or higher:

python --version

FileNotFoundError or path-related errors

Check your .env file and ensure all configured paths exist. See Environment Variables for the full list.

PermissionError: [Errno 13] Permission denied

Ensure you have read/write permissions for all configured directories and files.

MCP client integration

Server not appearing in Claude Desktop

Check the configuration file:

macOS:

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

Windows:

type %APPDATA%\Claude\claude_desktop_config.json

Ensure it contains:

{
    "mcpServers": {
        "kicad": {
            "command": "/ABSOLUTE/PATH/TO/kicad-mcp/.venv/bin/python",
            "args": [
                "/ABSOLUTE/PATH/TO/kicad-mcp/main.py"
            ]
        }
    }
}

Always use absolute paths. Replace:

"args": ["main.py"]

with:

"args": ["/absolute/path/to/main.py"]

Restart Claude Desktop after editing the configuration.

Protocol version mismatch -- update both the client and server to compatible versions.

KiCad integration

KiCad Python modules not found

Warning messages about missing KiCad Python modules indicate limited functionality for some features. Solutions:

1. Install KiCad from kicad.org
2. Set KICAD_APP_PATH for non-standard installations
3. Check server logs for Python path setup errors

Unable to open projects

1. Verify KiCad is installed and KICAD_APP_PATH is correct
2. Double-check the project file path (use absolute paths)
3. Ensure the file has a .kicad_pro extension
4. Check file and application permissions

Project discovery

Projects not found

1. Configure search paths in .env:

   KICAD_SEARCH_PATHS=~/pcb,~/Electronics,~/Projects/KiCad
   

2. Set KICAD_USER_DIR if using a custom directory:

   KICAD_USER_DIR=~/Documents/KiCadProjects
   

3. Ensure projects have the .kicad_pro extension
4. Restart the server after configuration changes

DRC and export issues

DRC checks failing

1. Ensure your project contains a .kicad_pcb file
2. Verify kicad-cli is available:

   which kicad-cli
   

   Or set KICAD_CLI_PATH in .env
3. Verify the PCB file can be opened in KiCad

Export tools failing

1. Check kicad-cli availability (same as DRC)
2. Verify the source file exists and is valid
3. Check write permissions in the output directory

PCB thumbnail/SVG generation failing

1. Ensure the project has a valid .kicad_pcb file
2. Check that kicad-cli supports SVG export (KiCad 9+)
3. Use absolute file paths

Logging and debugging

Checking logs

mckicad writes logs to mckicad.log in the project root, overwritten on each start.

For Claude Desktop logs:

macOS:

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

Windows: check %APPDATA%\Claude\Logs\

Using the MCP Inspector

For interactive debugging, use the MCP Inspector:

npx @modelcontextprotocol/inspector uv --directory . run main.py

This lets you call tools directly and inspect responses without going through an AI client.

Platform-specific issues

macOS

Permission denied accessing files -- ensure Terminal has full disk access in System Preferences > Security & Privacy.

System Python vs Homebrew Python -- specify the full path to the Python interpreter in your client configuration. Use the .venv/bin/python from make install.

Windows

Path separator issues -- use forward slashes (/) in all paths, or double backslashes (\\).

Cannot launch KiCad -- ensure KICAD_APP_PATH is set correctly in .env.

Linux

Non-standard KiCad location -- set KICAD_APP_PATH to your installation path.

Permission issues -- check file permissions with ls -la and adjust with chmod if needed.

Still having issues?

1. Use the MCP Inspector for direct tool testing
2. Check mckicad.log for detailed error information
3. Set LOG_LEVEL=DEBUG in .env for verbose logging
4. Open an issue with:
   • Clear description of the problem
   • Steps to reproduce
   • Error messages or log excerpts
   • Environment details (OS, Python version, KiCad version)