---
title: "Troubleshooting"
description: "Common issues and solutions for the mckicad server"
---

## Server setup issues

### Server not starting

**`ModuleNotFoundError: No module named 'mcp'`**

Dependencies are not installed. Run:

```bash
make install
```

**Syntax errors or unsupported features**

Verify you are using Python 3.10 or higher:

```bash
python --version
```

**`FileNotFoundError` or path-related errors**

Check your `.env` file and ensure all configured paths exist. See [Environment Variables](/reference/environment/) 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:
```bash
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

Windows:
```
type %APPDATA%\Claude\claude_desktop_config.json
```

Ensure it contains:

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

**Always use absolute paths.** Replace:

```json
"args": ["main.py"]
```

with:

```json
"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](https://www.kicad.org/download/)
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:
   ```bash
   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:
```bash
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:

```bash
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)