kicad-mcp

# KiCad MCP Server This guide will help you set up a Model Context Protocol (MCP) server for KiCad. While the examples in this guide often reference Claude Desktop, the server is compatible with **any MCP-compliant client**. You can use it with Claude Desktop, your own custom MCP clients, or any other application that implements the Model Context Protocol. ## Table of Contents - [Prerequisites](#prerequisites) - [Installation Steps](#installation-steps) - [Understanding MCP Components](#understanding-mcp-components) - [Feature Highlights](#feature-highlights) - [Natural Language Interaction](#natural-language-interaction) - [Documentation](#documentation) - [Configuration](#configuration) - [Development Guide](#development-guide) - [Troubleshooting](#troubleshooting) - [Contributing](#contributing) - [Future Development Ideas](#future-development-ideas) - [License](#license) ## Prerequisites - macOS, Windows, or Linux - Python 3.10 or higher - KiCad 9.0 or higher - uv 0.8.0 or higher - Claude Desktop (or another MCP client) ## Installation Steps ### 1. Set Up Your Python Environment First, let's install dependencies and set up our environment: ```bash # Clone the repository git clone https://github.com/lamaalrajih/kicad-mcp.git cd kicad-mcp # Install dependencies – `uv` will create a `.venv/` folder automatically # (Install `uv` first: `brew install uv` on macOS or `pipx install uv`) make install # Optional: activate the environment for manual commands source .venv/bin/activate ``` ### 2. Configure Your Environment Create a `.env` file to customize where the server looks for your KiCad projects: ```bash # Copy the example environment file cp .env.example .env # Edit the .env file vim .env ``` In the `.env` file, add your custom project directories: ``` # Add paths to your KiCad projects (comma-separated) KICAD_SEARCH_PATHS=~/pcb,~/Electronics,~/Projects/KiCad ``` ### 3. Run the Server Once the environment is set up, you can run the server: ```bash python main.py ``` ### 4. Configure an MCP Client Now, let's configure Claude Desktop to use our MCP server: 1. Create or edit the Claude Desktop configuration file: ```bash # Create the directory if it doesn't exist mkdir -p ~/Library/Application\ Support/Claude # Edit the configuration file vim ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` 2. Add the KiCad MCP server to the 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" ] } } } ``` Replace `/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp` with the actual path to your project directory. ### 5. Restart Your MCP Client Close and reopen your MCP client to load the new configuration. ## Understanding MCP Components The Model Context Protocol (MCP) defines three primary ways to provide capabilities: ### Resources vs Tools vs Prompts **Resources** are read-only data sources that LLMs can reference: - Similar to GET endpoints in REST APIs - Provide data without performing significant computation - Used when the LLM needs to read information - Typically accessed programmatically by the client application - Example: `kicad://projects` returns a list of all KiCad projects **Tools** are functions that perform actions or computations: - Similar to POST/PUT endpoints in REST APIs - Can have side effects (like opening applications or generating files) - Used when the LLM needs to perform actions in the world - Typically invoked directly by the LLM (with user approval) - Example: `open_project()` launches KiCad with a specific project **Prompts** are reusable templates for common interactions: - Pre-defined conversation starters or instructions - Help users articulate common questions or tasks - Invoked by user choice (typically from a menu) - Example: The `debug_pcb_issues` prompt helps users troubleshoot PCB problems For more information on resources vs tools vs prompts, read the [MCP docs](https://modelcontextprotocol.io/docs/concepts/architecture). ## Feature Highlights The KiCad MCP Server provides several key features, each with detailed documentation: - **Project Management**: List, examine, and open KiCad projects - *Example:* "Show me all my recent KiCad projects" → Lists all projects sorted by modification date - **PCB Design Analysis**: Get insights about your PCB designs and schematics - *Example:* "Analyze the component density of my temperature sensor board" → Provides component spacing analysis - **Netlist Extraction**: Extract and analyze component connections from schematics - *Example:* "What components are connected to the MCU in my Arduino shield?" → Shows all connections to the microcontroller - **BOM Management**: Analyze and export Bills of Materials - *Example:* "Generate a BOM for my smart watch project" → Creates a detai