KiCad MCP Server
Integrates with .env files for configuration, allowing users to customize KiCad project search paths and other server settings through environment variables.
Provides tools for KiCad PCB design projects including listing projects, viewing project details, running Design Rule Checks (DRC), generating PCB thumbnails, and launching KiCad applications with specific projects.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@KiCad MCP Server analyze the component density of my temperature sensor board"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: kicad-mcp
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:
# 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/activate2. 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 .envIn the .env file, add your custom project directories:
# Add paths to your KiCad projects (comma-separated)
KICAD_SEARCH_PATHS=~/pcb,~/Electronics,~/Projects/KiCad3. Run the Server
Once the environment is set up, you can run the server:
python main.py4. Configure an MCP Client
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.jsonAdd 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.
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://projectsreturns 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_issuesprompt helps users troubleshoot PCB problems
For more information on resources vs tools vs prompts, read the MCP docs.
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 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!
Natural Language Interaction
While our documentation often shows examples like:
Show me the DRC report for /Users/username/Documents/KiCad/my_project/my_project.kicad_proYou 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?Or:
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.
Documentation
Detailed documentation for each feature is available in the docs/ directory:
Configuration
The KiCad MCP Server can be configured using environment variables or a .env file:
Key Configuration Options
Environment Variable | Description | Example |
| Comma-separated list of directories to search for KiCad projects |
|
| Override the default KiCad user directory |
|
| Override the default KiCad application path |
|
See Configuration Guide for more details.
Development Guide
Project Structure
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 testsAdding New Features
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
See Development Guide for more details.
Troubleshooting
If you encounter issues:
Server Not Appearing in MCP Client:
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
mcppackageCheck if your KiCad installation is detected
Server Errors:
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)
Working Directory Issues:
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 Troubleshooting Guide for more details.
If you're still not able to troubleshoot, please open a Github issue.
Contributing
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
Key areas for contribution:
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 CONTRIBUTING.md for detailed contribution guidelines.
Future Development Ideas
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
License
This project is open source under the MIT license.
Available Tools
16 toolsanalyze_bomB
Analyze a KiCad project's Bill of Materials.
This tool will look for BOM files related to a KiCad project and provide analysis including component counts, categories, and cost estimates if available.
Args: project_path: Path to the KiCad project file (.kicad_pro) ctx: MCP context for progress reporting
Returns: Dictionary with BOM analysis results
Inputs: project_path (required), ctx (required). Returns: object
analyze_project_circuit_patternsC
Identify circuit patterns in a KiCad project's schematic.
Args: project_path: Path to the KiCad project file (.kicad_pro) ctx: MCP context for progress reporting
Returns: Dictionary with identified circuit patterns
Inputs: project_path (required), ctx (required). Returns: object
analyze_schematic_connectionsB
Analyze connections in a KiCad schematic.
This tool provides detailed analysis of component connections, including power nets, signal paths, and potential issues.
Args: schematic_path: Path to the KiCad schematic file (.kicad_sch) ctx: MCP context for progress reporting
Returns: Dictionary with connection analysis
Inputs: schematic_path (required), ctx (required). Returns: object
export_bom_csvB
Export a Bill of Materials for a KiCad project.
This tool attempts to generate a CSV BOM file for a KiCad project. It requires KiCad to be installed with the appropriate command-line tools.
Args: project_path: Path to the KiCad project file (.kicad_pro) ctx: MCP context for progress reporting
Returns: Dictionary with export results
Inputs: project_path (required), ctx (required). Returns: object
extract_project_netlistC
Extract netlist from a KiCad project's schematic.
This tool finds the schematic associated with a KiCad project and extracts its netlist information.
Args: project_path: Path to the KiCad project file (.kicad_pro) ctx: MCP context for progress reporting
Returns: Dictionary with netlist information
Inputs: project_path (required), ctx (required). Returns: object
extract_schematic_netlistB
Extract netlist information from a KiCad schematic.
This tool parses a KiCad schematic file and extracts comprehensive netlist information including components, connections, and labels.
Args: schematic_path: Path to the KiCad schematic file (.kicad_sch) ctx: MCP context for progress reporting
Returns: Dictionary with netlist information
Inputs: schematic_path (required), ctx (required). Returns: object
find_component_connectionsA
Find all connections for a specific component in a KiCad project.
This tool extracts information about how a specific component is connected to other components in the schematic.
Args: project_path: Path to the KiCad project file (.kicad_pro) component_ref: Component reference (e.g., "R1", "U3") ctx: MCP context for progress reporting
Returns: Dictionary with component connection information
Inputs: project_path (required), component_ref (required), ctx (required). Returns: object
generate_pcb_thumbnailC
Generate a thumbnail image of a KiCad PCB layout using kicad-cli.
Args: project_path: Path to the KiCad project file (.kicad_pro) ctx: Context for MCP communication
Returns: Thumbnail image of the PCB or None if generation failed
Inputs: project_path (required), ctx (required).
generate_project_thumbnailC
Generate a thumbnail of a KiCad project's PCB layout (Alias for generate_pcb_thumbnail).
Inputs: project_path (required), ctx (required).
get_drc_history_toolB
Get the DRC check history for a KiCad project.
Args: project_path: Path to the KiCad project file (.kicad_pro)
Returns: Dictionary with DRC history entries
Inputs: project_path (required). Returns: object
get_project_structureB
Get the structure and files of a KiCad project.
Inputs: project_path (required). Returns: object
identify_circuit_patternsA
Identify common circuit patterns in a KiCad schematic.
This tool analyzes a schematic to recognize common circuit blocks such as:
Power supply circuits (linear regulators, switching converters)
Amplifier circuits (op-amps, transistor amplifiers)
Filter circuits (RC, LC, active filters)
Digital interfaces (I2C, SPI, UART)
Microcontroller circuits
And more
Args: schematic_path: Path to the KiCad schematic file (.kicad_sch) ctx: MCP context for progress reporting
Returns: Dictionary with identified circuit patterns
Inputs: schematic_path (required), ctx (required). Returns: object
list_projectsB
Find and list all KiCad projects on this system.
Inputs: no named parameters. Returns: result
open_projectC
Open a KiCad project in KiCad.
Inputs: project_path (required). Returns: object
run_drc_checkB
Run a Design Rule Check on a KiCad PCB file.
Args: project_path: Path to the KiCad project file (.kicad_pro) ctx: MCP context for progress reporting
Returns: Dictionary with DRC results and statistics
Inputs: project_path (required), ctx (required). Returns: object
validate_projectC
Basic validation of a KiCad project.
Inputs: project_path (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
There is significant overlap between several tools, particularly in the analysis and extraction categories. For example, analyze_schematic_connections and find_component_connections both deal with connections, while extract_project_netlist and extract_schematic_netlist have unclear boundaries. However, the descriptions help clarify some distinctions, preventing complete confusion.
Most tools follow a consistent verb_noun pattern (e.g., analyze_bom, export_bom_csv, list_projects), which is clear and predictable. There are minor deviations like get_drc_history_tool (redundant 'tool' suffix) and generate_pcb_thumbnail (slightly different structure), but overall the naming is coherent and readable.
With 16 tools, the count is slightly high but reasonable for a KiCad server covering project management, analysis, and export functions. It feels comprehensive rather than bloated, though some consolidation might improve focus. The scope justifies most tools, but it borders on being heavy.
The toolset covers key areas like project listing, validation, analysis, and export, with good lifecycle coverage for KiCad workflows. Minor gaps exist, such as no direct PCB editing or schematic modification tools, but agents can likely work around these with the provided analysis and validation tools for a complete design process.
Maintenance
Related MCP Connectors
Design, route, check, review and export manufacturable PCBs from plain language; KiCad import.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Design and revise PCBs from plain language, track jobs, and retrieve design artifacts.
A Model Context Protocol server for Wix AI tools
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceA typed Model Context Protocol server that exposes KiCad 10 EDA workflows to language-model clients through validated tool calls.MIT
- AlicenseNot gradedqualityDmaintenanceEnables natural language interaction with KiCad projects, schematics, and PCBs, supporting project management, design rule checking, netlist extraction, and datasheet RAG search.3MIT
- AlicenseBqualityBmaintenanceAn MCP server that enables AI assistants to analyze schematics, inspect PCBs, trace connections, validate designs, and generate embedded code for KiCad projects.39188MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with KiCAD for PCB design automation.MIT