# KiCad MCP Server

A Model Context Protocol (MCP) server that exposes KiCad PCB design automation tools to AI assistants and other MCP clients.

# KiCad MCP Server

Exposes KiCad's Python API (`pcbnew`) and CLI commands via an MCP server.

## Features

- Create new PCB projects
- Add footprints
- Run DRC
- Export Gerbers
- Get PCB information
- Export BOM
- Execute arbitrary KiCad CLI commands

## Usage

Run the server:

```bash
python -m kicad_mcp_server.server


## Features

- **PCB Project Management**: Create new PCB projects
- **Footprint Operations**: Add and manage footprints programmatically
- **Design Rule Check**: Run DRC and get violation reports
- **Manufacturing Export**: Export Gerber files for PCB manufacturing
- **Board Analysis**: Get board information and footprint listings
- **BOM Export**: Generate Bill of Materials from schematics
- **CLI Integration**: Execute arbitrary KiCad CLI commands

## Prerequisites

1. **KiCad 7.0 or later** installed on your system
2. **Python 3.10+**
3. **KiCad CLI** in your system PATH
4. **(Optional)** KiCad Python API (pcbnew) for advanced features

### Installing KiCad

- **Windows**: Download from [KiCad.org](https://www.kicad.org/download/)
- **macOS**: `brew install kicad`
- **Linux**: `sudo apt install kicad` or equivalent

### Verifying KiCad CLI

```bash
kicad-cli --version
```

## Installation

### 1. Clone or Create Project Structure

```bash
mkdir kicad-mcp-server
cd kicad-mcp-server
```

Create the following structure:
```
kicad-mcp-server/
├── kicad_mcp_server/
│   ├── __init__.py
│   └── server.py
├── pyproject.toml
├── requirements.txt
├── README.md
└── .env (optional)
```

### 2. Install Dependencies

```bash
# Create virtual environment
python -m venv venv

# Activate it
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .
```

### 3. (Optional) Enable KiCad Python API

The pcbnew module comes with KiCad but may need to be added to Python path:

**Windows:**
```bash
set PYTHONPATH=C:\Program Files\KiCad\7.0\bin\Lib\site-packages;%PYTHONPATH%
```

**macOS:**
```bash
export PYTHONPATH="/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/lib/python3.9/site-packages:$PYTHONPATH"
```

**Linux:**
```bash
export PYTHONPATH="/usr/lib/kicad/lib/python3/dist-packages:$PYTHONPATH"
```

## Configuration

### Claude Desktop Configuration

Add to your Claude Desktop config file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "kicad": {
      "command": "python",
      "args": [
        "-m",
        "kicad_mcp_server.server"
      ],
      "env": {
        "PYTHONPATH": "/path/to/kicad/python/packages"
      }
    }
  }
}
```

### For Other MCP Clients

If using with other MCP clients, start the server:

```bash
python -m kicad_mcp_server.server
```

The server communicates via stdio following the MCP protocol.

## Available Tools

### 1. create_new_pcb
Create a new KiCad PCB project.

**Parameters:**
- `project_name` (string): Name of the project
- `project_path` (string): Directory path

**Example:**
```
Create a new PCB project called "my-board" in /home/user/projects
```

### 2. add_footprint
Add a footprint to an existing PCB.

**Parameters:**
- `pcb_file` (string): Path to .kicad_pcb file
- `footprint_library` (string): Library name (e.g., "Resistor_SMD")
- `footprint_name` (string): Footprint name (e.g., "R_0805_2012Metric")
- `x` (number): X coordinate in mm
- `y` (number): Y coordinate in mm
- `reference` (string): Reference designator (e.g., "R1")

**Example:**
```
Add a 0805 resistor footprint at position (50, 50) with reference R1
```

### 3. run_drc
Run Design Rule Check on a PCB.

**Parameters:**
- `pcb_file` (string): Path to .kicad_pcb file

**Example:**
```
Run DRC on my-board.kicad_pcb
```

### 4. export_gerbers
Export Gerber files for manufacturing.

**Parameters:**
- `pcb_file` (string): Path to .kicad_pcb file
- `output_dir` (string): Output directory

**Example:**
```
Export gerbers from my-board.kicad_pcb to ./gerbers/
```

### 5. get_board_info
Get information about a PCB.

**Parameters:**
- `pcb_file` (string): Path to .kicad_pcb file

**Example:**
```
Get board info for my-board.kicad_pcb
```

### 6. list_footprints
List all footprints and their positions.

**Parameters:**
- `pcb_file` (string): Path to .kicad_pcb file

**Example:**
```
List all footprints in my-board.kicad_pcb
```

### 7. export_bom
Export Bill of Materials.

**Parameters:**
- `schematic_file` (string): Path to .kicad_sch file
- `output_file` (string): Output CSV path

**Example:**
```
Export BOM from my-board.kicad_sch to bom.csv
```

### 8. kicad_cli_command
Execute arbitrary KiCad CLI command.

**Parameters:**
- `command` (string): Command (e.g., "pcb export step")
- `args` (array): Command arguments

**Example:**
```
Execute kicad-cli command: pcb export step with args [my-board.kicad_pcb, output.step]
```

## Usage Examples

### With Claude Desktop

Once configured, you can ask Claude:

```
"Create a new PCB project called 'led-blinker' in my Documents folder"

"Add a 0805 resistor footprint at position (25, 25) with reference R1 to led-blinker.kicad_pcb"

"Run DRC on my board and tell me if there are any violations"

"Export gerbers for manufacturing from my-board.kicad_pcb"

"What are the dimensions of my board?"
```

### Testing the Server

```python
# test_server.py
import asyncio
import json
from kicad_mcp_server.server import handle_call_tool

async def test():
    # Test creating a project
    result = await handle_call_tool(
        "create_new_pcb",
        {
            "project_name": "test-board",
            "project_path": "./test-projects"
        }
    )
    print(result[0].text)

asyncio.run(test())
```

## Project Structure

```
kicad-mcp-server/
├── kicad_mcp_server/
│   ├── __init__.py          # Package init
│   └── server.py            # Main MCP server implementation
├── tests/
│   ├── __init__.py
│   └── test_server.py       # Unit tests
├── examples/
│   └── example_usage.py     # Usage examples
├── pyproject.toml           # Project metadata
├── requirements.txt         # Dependencies
├── README.md               # This file
└── LICENSE                 # License file
```

## Troubleshooting

### "pcbnew module not found"
- Install KiCad Python API or add KiCad's Python packages to PYTHONPATH
- Some features work without pcbnew using CLI fallbacks

### "kicad-cli not found"
- Ensure KiCad CLI is installed and in your system PATH
- Test with: `kicad-cli --version`

### "Command failed" errors
- Check that file paths are correct and files exist
- Ensure KiCad files are not open in KiCad (may cause file locks)
- Check KiCad CLI output for specific errors

### Permission errors
- Ensure you have write permissions to output directories
- On Linux/macOS, check file permissions with `ls -la`

## Development

### Running Tests
```bash
pytest tests/
```

### Code Formatting
```bash
black kicad_mcp_server/
```

### Type Checking
```bash
mypy kicad_mcp_server/
```

## Extending the Server

To add new tools:

1. Add tool definition in `handle_list_tools()`
2. Add handler in `handle_call_tool()`
3. Implement the function following the async pattern
4. Update README documentation

Example:
```python
async def my_new_tool(args: dict) -> list[TextContent]:
    # Your implementation
    return [TextContent(type="text", text="Result")]
```

## Limitations

- Schematic editing is limited (KiCad's Python API focuses on PCB)
- Some advanced features require pcbnew module
- CLI commands may vary between KiCad versions
- Real-time GUI integration not supported

## Contributing

Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Submit a pull request

## License

MIT License - see LICENSE file

## Resources

- [KiCad Documentation](https://docs.kicad.org/)
- [KiCad Python API](https://docs.kicad.org/doxygen-python/namespacepcbnew.html)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)

## Support