Skip to content
Back to search

kicad-mcp

Model Context Protocol server for KiCad on Mac, Windows, and Linux

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lamaalrajih--kicad-mcp/badge.svg)](/listings/lamaalrajih--kicad-mcp)

HTML

<a href="/listings/lamaalrajih--kicad-mcp"><img src="/api/listings/lamaalrajih--kicad-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Set Up Your Python Environment

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

2. Configure Your Environment

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

3. Run the Server

Once the environment is set up, you can run the server:

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:

# 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:

{
    "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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 309 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # KiCad MCP Server
  2. 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.
  3. ## Table of Contents
  4. - [Prerequisites](#prerequisites)
  5. - [Installation Steps](#installation-steps)
  6. - [Understanding MCP Components](#understanding-mcp-components)
  7. - [Feature Highlights](#feature-highlights)
  8. - [Natural Language Interaction](#natural-language-interaction)
  9. - [Documentation](#documentation)
  10. - [Configuration](#configuration)
  11. - [Development Guide](#development-guide)
  12. - [Troubleshooting](#troubleshooting)
  13. - [Contributing](#contributing)
  14. - [Future Development Ideas](#future-development-ideas)
  15. - [License](#license)
  16. ## Prerequisites
  17. - macOS, Windows, or Linux
  18. - Python 3.10 or higher
  19. - KiCad 9.0 or higher
  20. - uv 0.8.0 or higher
  21. - Claude Desktop (or another MCP client)
  22. ## Installation Steps
  23. ### 1. Set Up Your Python Environment
  24. First, let's install dependencies and set up our environment:
  25. ```bash
  26. # Clone the repository
  27. git clone https://github.com/lamaalrajih/kicad-mcp.git
  28. cd kicad-mcp
  29. # Install dependencies – `uv` will create a `.venv/` folder automatically
  30. # (Install `uv` first: `brew install uv` on macOS or `pipx install uv`)
  31. make install
  32. # Optional: activate the environment for manual commands
  33. source .venv/bin/activate
  34. ```
  35. ### 2. Configure Your Environment
  36. Create a `.env` file to customize where the server looks for your KiCad projects:
  37. ```bash
  38. # Copy the example environment file
  39. cp .env.example .env
  40. # Edit the .env file
  41. vim .env
  42. ```
  43. In the `.env` file, add your custom project directories:
  44. ```
  45. # Add paths to your KiCad projects (comma-separated)
  46. KICAD_SEARCH_PATHS=~/pcb,~/Electronics,~/Projects/KiCad
  47. ```
  48. ### 3. Run the Server
  49. Once the environment is set up, you can run the server:
  50. ```bash
  51. python main.py
  52. ```
  53. ### 4. Configure an MCP Client
  54. Now, let's configure Claude Desktop to use our MCP server:
  55. 1. Create or edit the Claude Desktop configuration file:
  56. ```bash
  57. # Create the directory if it doesn't exist
  58. mkdir -p ~/Library/Application\ Support/Claude
  59. # Edit the configuration file
  60. vim ~/Library/Application\ Support/Claude/claude_desktop_config.json
  61. ```
  62. 2. Add the KiCad MCP server to the configuration:
  63. ```json
  64. {
  65. "mcpServers": {
  66. "kicad": {
  67. "command": "/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/.venv/bin/python",
  68. "args": [
  69. "/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/main.py"
  70. ]
  71. }
  72. }
  73. }
  74. ```
  75. Replace `/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp` with the actual path to your project directory.
  76. ### 5. Restart Your MCP Client
  77. Close and reopen your MCP client to load the new configuration.
  78. ## Understanding MCP Components
  79. The Model Context Protocol (MCP) defines three primary ways to provide capabilities:
  80. ### Resources vs Tools vs Prompts
  81. **Resources** are read-only data sources that LLMs can reference:
  82. - Similar to GET endpoints in REST APIs
  83. - Provide data without performing significant computation
  84. - Used when the LLM needs to read information
  85. - Typically accessed programmatically by the client application
  86. - Example: `kicad://projects` returns a list of all KiCad projects
  87. **Tools** are functions that perform actions or computations:
  88. - Similar to POST/PUT endpoints in REST APIs
  89. - Can have side effects (like opening applications or generating files)
  90. - Used when the LLM needs to perform actions in the world
  91. - Typically invoked directly by the LLM (with user approval)
  92. - Example: `open_project()` launches KiCad with a specific project
  93. **Prompts** are reusable templates for common interactions:
  94. - Pre-defined conversation starters or instructions
  95. - Help users articulate common questions or tasks
  96. - Invoked by user choice (typically from a menu)
  97. - Example: The `debug_pcb_issues` prompt helps users troubleshoot PCB problems
  98. For more information on resources vs tools vs prompts, read the [MCP docs](https://modelcontextprotocol.io/docs/concepts/architecture).
  99. ## Feature Highlights
  100. The KiCad MCP Server provides several key features, each with detailed documentation:
  101. - **Project Management**: List, examine, and open KiCad projects
  102. - *Example:* "Show me all my recent KiCad projects" → Lists all projects sorted by modification date
  103. - **PCB Design Analysis**: Get insights about your PCB designs and schematics
  104. - *Example:* "Analyze the component density of my temperature sensor board" → Provides component spacing analysis
  105. - **Netlist Extraction**: Extract and analyze component connections from schematics
  106. - *Example:* "What components are connected to the MCU in my Arduino shield?" → Shows all connections to the microcontroller
  107. - **BOM Management**: Analyze and export Bills of Materials
  108. - *Example:* "Generate a BOM for my smart watch project" → Creates a detailed bill of materials
  109. - **Design Rule Checking**: Run DRC checks using the KiCad CLI and track your progress over time
  110. - *Example:* "Run DRC on my power supply board and compare to last week" → Shows progress in fixing violations
  111. - **PCB Visualization**: Generate visual representations of your PCB layouts
  112. - *Example:* "Show me a thumbnail of my audio amplifier PCB" → Displays a visual render of the board
  113. - **Circuit Pattern Recognition**: Automatically identify common circuit patterns in your schematics
  114. - *Example:* "What power supply topologies am I using in my IoT device?" → Identifies buck, boost, or linear regulators
  115. 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!
  116. ## Natural Language Interaction
  117. While our documentation often shows examples like:
  118. ```
  119. Show me the DRC report for /Users/username/Documents/KiCad/my_project/my_project.kicad_pro
  120. ```
  121. You don't need to type the full path to your files! The LLM can understand more natural language requests.
  122. For example, instead of the formal command above, you can simply ask:
  123. ```
  124. Can you check if there are any design rule violations in my Arduino shield project?
  125. ```
  126. Or:
  127. ```
  128. I'm working on the temperature sensor circuit. Can you identify what patterns it uses?
  129. ```
  130. 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.
  131. ## Documentation
  132. Detailed documentation for each feature is available in the `docs/` directory:
  133. - [Project Management](docs/project_guide.md)
  134. - [PCB Design Analysis](docs/analysis_guide.md)
  135. - [Netlist Extraction](docs/netlist_guide.md)
  136. - [Bill of Materials (BOM)](docs/bom_guide.md)
  137. - [Design Rule Checking (DRC)](docs/drc_guide.md)
  138. - [PCB Visualization](docs/thumbnail_guide.md)
  139. - [Circuit Pattern Recognition](docs/pattern_guide.md)
  140. - [Prompt Templates](docs/prompt_guide.md)
  141. ## Configuration
  142. The KiCad MCP Server can be configured using environment variables or a `.env` file:
  143. ### Key Configuration Options
  144. | Environment Variable | Description | Example |
  145. |---------------------|-------------|---------|
  146. | `KICAD_SEARCH_PATHS` | Comma-separated list of directories to search for KiCad projects | `~/pcb,~/Electronics,~/Projects` |
  147. | `KICAD_USER_DIR` | Override the default KiCad user directory | `~/Documents/KiCadProjects` |
  148. | `KICAD_APP_PATH` | Override the default KiCad application path | `/Applications/KiCad7/KiCad.app` |
  149. See [Configuration Guide](docs/configuration.md) for more details.
  150. ## Development Guide
  151. ### Project Structure
  152. The KiCad MCP Server is organized into a modular structure:
  153. ```
  154. kicad-mcp/
  155. ├── README.md # Project documentation
  156. ├── main.py # Entry point that runs the server
  157. ├── requirements.txt # Python dependencies
  158. ├── .env.example # Example environment configuration
  159. ├── kicad_mcp/ # Main package directory
  160. │ ├── __init__.py
  161. │ ├── server.py # MCP server setup
  162. │ ├── config.py # Configuration constants and settings
  163. │ ├── context.py # Lifespan management and shared context
  164. │ ├── resources/ # Resource handlers
  165. │ ├── tools/ # Tool handlers
  166. │ ├── prompts/ # Prompt templates
  167. │ └── utils/ # Utility functions
  168. ├── docs/ # Documentation
  169. └── tests/ # Unit tests
  170. ```
  171. ### Adding New Features
  172. To add new features to the KiCad MCP Server, follow these steps:
  173. 1. Identify the category for your feature (resource, tool, or prompt)
  174. 2. Add your implementation to the appropriate module
  175. 3. Register your feature in the corresponding register function
  176. 4. Test your changes with the development tools
  177. See [Development Guide](docs/development.md) for more details.
  178. ## Troubleshooting
  179. If you encounter issues:
  180. 1. **Server Not Appearing in MCP Client:**
  181. - Check your client's configuration file for errors
  182. - Make sure the path to your project and Python interpreter is correct
  183. - Ensure Python can access the `mcp` package
  184. - Check if your KiCad installation is detected
  185. 2. **Server Errors:**
  186. - Check the terminal output when running the server in development mode
  187. - Check Claude logs at:
  188. - `~/Library/Logs/Claude/mcp-server-kicad.log` (server-specific logs)
  189. - `~/Library/Logs/Claude/mcp.log` (general MCP logs)
  190. 3. **Working Directory Issues:**
  191. - The working directory for servers launched via client configs may be undefined
  192. - Always use absolute paths in your configuration and .env files
  193. - For testing servers via command line, the working directory will be where you run the command
  194. See [Troubleshooting Guide](docs/troubleshooting.md) for more details.
  195. If you're still not able to troubleshoot, please open a Github issue.
  196. ## Contributing
  197. Want to contribute to the KiCad MCP Server? Here's how you can help improve this project:
  198. 1. Fork the repository
  199. 2. Create a feature branch
  200. 3. Add your changes
  201. 4. Submit a pull request
  202. Key areas for contribution:
  203. - Adding support for more component patterns in the Circuit Pattern Recognition system
  204. - Improving documentation and examples
  205. - Adding new features or enhancing existing ones
  206. - Fixing bugs and improving error handling
  207. See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.
  208. ## Future Development Ideas
  209. Interested in contributing? Here are some ideas for future development:
  210. 1. **3D Model Visualization** - Implement tools to visualize 3D models of PCBs
  211. 2. **PCB Review Tools** - Create annotation features for design reviews
  212. 3. **Manufacturing File Generation** - Add support for generating Gerber files and other manufacturing outputs
  213. 4. **Component Search** - Implement search functionality for components across KiCad libraries
  214. 5. **BOM Enhancement** - Add supplier integration for component sourcing and pricing
  215. 6. **Interactive Design Checks** - Develop interactive tools for checking design quality
  216. 7. **Web UI** - Create a simple web interface for configuration and monitoring
  217. 8. **Circuit Analysis** - Add automated circuit analysis features
  218. 9. **Test Coverage** - Improve test coverage across the codebase
  219. 10. **Circuit Pattern Recognition** - Expand the pattern database with more component types and circuit topologies
  220. ## License
  221. This project is open source under the MIT license.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.