KiCad

An MCP server for KiCad providing project management, PCB design analysis, BOM management, and design rule checking. 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. - [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 - 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) First, let's install dependencies and set up our environment: ``` `# 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` ``` Create a`.env`file to customize where the server looks for your KiCad projects: ``` `# 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` ``` Once the environment is set up, you can run the server: Now, let's configure Claude Desktop to use our MCP server: - Create or edit the Claude Desktop configuration file: ``` `# 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` ``` - Add the KiCad MCP server to the configuration: ``` `{ "mcpServers": { "kicad": { "command": "/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/.venv/bin/python", "args": ](#license)[ "/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. Close and reopen your MCP client to load the new configuration. The Model Context Protocol (MCP) defines three primary ways to provide capabilities: **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. 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 detailed bill of materials **Design Rule Checking**: Run DRC checks using the KiCad CLI and track your progress over time *Example:*"Run DRC on my power supply board and compare to last week" → Shows progress in fixing violations **PCB Visualization**: Generate visual representations of your PCB layouts - *Example:*"Show me a thumbnail of my audio amplifier PCB" → Displays a visual render of the board **Circuit Pattern Recognition**: Automatically identify common circuit patterns in your schematics - *Example:*"What power supply topologies am I using in my IoT device?" → Identifies buck, boost, or linear regulators For more examples and details on each feature, see the dedicated guides in the documentation. You can also ask the LLM what tools it has access to! While our documentation often shows examples like: ``` `Show me the DRC report for /Users/username/Documents/KiCad/my_project/my_project.kicad_pro` ``` You don't need to type the full path to your files! The LLM can understand more natural language requests. For example, instead of the formal command above, you can simply ask: ``` `Can you check if there are any design rule violations in my Arduino shield project?` ``` ``` `I'm working on the temperature sensor circuit. Can you identify what patterns it uses?` ``` The LLM will understand your intent and request the relevant information from the KiCad MCP Server. If it needs clarification about which project you're referring to, it will ask. Detailed documentation for each feature is available in the`docs/`directory: - ](https://modelcontextprotocol.io/docs/concepts/architecture)[Project Management - ](https://github.com/lamaalrajih/kicad-mcp/blob/HEAD/docs/project_guide.md)[PCB Design Analysis - ](https://github.com/lamaalrajih/kicad-mcp/blob/HEAD/docs/analysis_guide.md)[Netlist Extraction - ](https://github.com/lamaalrajih/kicad-mcp/blob/HEAD/docs/netlist_guide.md)[Bill of Materials (BOM) - ](https://github.com/lamaalrajih/kicad-mcp/blob/HEAD/docs/bom_guide.md)[Design Rule Checking (DRC) - ](https://github.com/lamaalrajih/kicad-mcp/blob/HEAD/docs/drc_guide.md)[PCB Visualization - ](https://github.com/lamaalrajih/kicad-mcp/blob/HEAD/docs/thumbnail_guide.md)[Circuit Pattern Recognition - ](https://github.com/lamaalrajih/kicad-mcp/blob/HEAD/docs/pattern_guide.md)[Prompt Templates The KiCad MCP Server can be configured using environment variables or a`.env`file: See](https://github.com/lamaalrajih/kicad-mcp/blob/HEAD/docs/prompt_guide.md)[Configuration Guidefor more details. The KiCad MCP Server is organized into a modular structure: ``` `kicad-mcp/ ├── README.md # Project documentation ├── main.py # Entry point that runs the server ├── requirements.txt # Python dependencies ├── .env.example # Example environment configuration ├── kicad_mcp/ # Main package directory │ ├── __init__.py │ ├── server.py # MCP server setup │ ├── config.py # Configuration constants and settings │ ├── context.py # Lifespan management and shared context │ ├── resources/ # Resource handlers │ ├── tools/ # Tool handlers │ ├── prompts/ # Prompt templates │ └── utils/ # Utility functions ├── docs/ # Documentation └── tests/ # Unit tests` ``` To add new features to the KiCad MCP Server, follow these steps: - Identify the category for your feature (resource, tool, or prompt) - Add your implementation to the appropriate module - Register your feature in the corresponding register function - Test your changes with the development tools - Check your client's configuration file for errors - Make sure the path to your project and Python interpreter is correct - Ensure Python can access the`mcp`package - Check if your KiCad installation is detected - Check the terminal output when running the server in development mode - Check Claude logs at: - `~/Library/Logs/Claude/mcp-server-kicad.log`(server-specific logs) - `~/Library/Logs/Claude/mcp.log`(general MCP logs) - The working directory for servers launched via client configs may be undefined - Always use absolute paths in your configuration and .env files - For testing servers via command line, the working directory will be where you run the command See](https://github.com/lamaalrajih/kicad-mcp/blob/HEAD/docs/configuration.md)[Troubleshooting Guidefor more details. If you're still not able to troubleshoot, please open a Github issue. Want to contribute to the KiCad MCP Server? Here's how you can help improve this project: - Fork the repository - Create a feature branch - Add your changes - Submit a pull request - Adding support for more component patterns in the Circuit Pattern Recognition system - Improving documentation and examples - Adding new features or enhancing existing ones - Fixing bugs and improving error handling See](https://github.com/lamaalrajih/kicad-mcp/blob/HEAD/docs/troubleshooting.md)[CONTRIBUTING.mdfor detailed contribution guidelines. Interested in contributing? Here are some ideas for future development: - **3D Model Visualization**- Implement tools to visualize 3D models of PCBs - **PCB Review Tools**- Create annotation features for design reviews - **Manufacturing File Generation**- Add support for generating Gerber files and other manufacturing outputs - **Component Search**- Implement search functionality for components across KiCad libraries - **BOM Enhancement**- Add supplier integration for component sourcing and pricing - **Interactive Design Checks**- Develop interactive tools for checking design quality - **Web UI**- Create a simple web interface for configuration and monitoring - **Circuit Analysis**- Add automated circuit analysis features - **Test Coverage**- Improve test coverage across the codebase - **Circuit Pattern Recognition**- Expand the pattern database with more component types and circuit topologies This project is open source under the MIT license. This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases. Create crafted UI components inspired by the best 21st.dev design engineers. Bring agent evaluations, observability, and synthetic test set generation directly into your IDE for free with Galileo's new MCP server An MCP server to help AI assistants to answer questions and generate AccelByte Extend SDK code more effectively . MCP server for AI Diagram Maker — generate beautiful software engineering diagrams directly inside Cursor, Claude Desktop, Claude Code, or any MCP-compatible AI agent ALAPI MCP Tools,Call hundreds of API interfaces via MCP AI-powered SVG animation generator that transforms static files into animated SVG components using the Allyson platform MCP server that gives AI assistants on-demand access to 1,500+ amCharts docs, ~300 code examples, and 1000+ class API references. APIMatic MCP Server is used to validate OpenAPI specifications using APIMatic. The server processes OpenAPI files and returns validation summaries by leveraging APIMatic’s API. One shared context layer for AI agents and humans — live API specs, DB schemas, and versioned contracts across repos so every agent and teammate works from the same source of truth.](https://github.com/lamaalrajih/kicad-mcp/blob/HEAD/CONTRIBUTING.md)