KiCad MCP Server

# KiCad MCP Server A Model Context Protocol (MCP) server that provides searchable access to KiCad component symbol libraries. Query your local KiCad libraries using natural language through Claude or other MCP-compatible clients. ## Features - **Fast full-text search** across 20,000+ KiCad components using SQLite FTS5 - **Component metadata** including references, values, descriptions, datasheets, and footprints - **Separate indexer and server** for optimal performance - **MCP-compliant** tools for integration with Claude Code and other MCP clients ## Installation ```bash # Clone the repository git clone https://github.com/yourusername/kicad_mcp.git cd kicad_mcp # Install using pip pip install -e . # Or install with development dependencies pip install -e ".[dev]" ``` ## Quick Start ### 1. Index Your KiCad Libraries First, build the component database from your KiCad symbol libraries: ```bash # Index default KiCad locations (/usr/share/kicad/symbols/) kicad-index # Or specify a custom directory kicad-index /path/to/your/symbols # Check database statistics kicad-index --stats ``` The database is stored at `~/.local/share/kicad-mcp/components.db`. ### 2. Configure MCP Server #### For Claude Code Add the server to your Claude Code configuration: ```bash claude mcp add --transport stdio kicad --scope user -- /path/to/kicad_mcp/.venv/bin/kicad-mcp ``` Or manually edit `~/.claude/claude_mcp_config.json`: ```json { "mcpServers": { "kicad": { "command": "/path/to/kicad_mcp/.venv/bin/kicad-mcp", "args": [] } } } ``` #### For Other MCP Clients The server communicates via stdio using the MCP protocol. Configure your client to launch `kicad-mcp` as a subprocess. ### 3. Use the Tools Once configured, you'll have access to these MCP tools: - `search_components` - Search by name, description, or keywords - `list_component_types` - Get all reference designator types (R, C, U, etc.) - `get_components_by_type` - Filter components by reference type - `get_component_details` - Get complete metadata for a specific component ## Examples ### Searching for Components ``` Find me an ATmega microcontroller -> Returns ATmega328, ATmega32U4, etc. with datasheets and footprints What capacitors are available? -> Lists capacitors with descriptions and package options I need a voltage regulator -> Shows LDOs, switching regulators, etc. ``` ### Component Details Each component includes: - **Name** - Component identifier - **Library** - Source KiCad library - **Reference** - Designator prefix (R, C, U, IC, etc.) - **Value** - Component value/model - **Description** - Human-readable description - **Keywords** - Searchable tags - **Datasheet** - URL to datasheet (if available) - **Footprint** - Associated PCB footprint ## Architecture This project uses a two-tool architecture: 1. **Indexer (`kicad-index`)** - Parses `.kicad_sym` files and builds a SQLite database with full-text search 2. **MCP Server (`kicad-mcp`)** - Long-running process that serves queries from the pre-built database This separation ensures fast server startup and allows updating the index independently. ## KiCad Library Locations Default search paths (Linux): - System libraries: `/usr/share/kicad/symbols/` - User libraries: `~/.local/share/kicad/9.0/symbols/` Adjust paths for your OS and KiCad version. ## Development ```bash # Create virtual environment (using uv) uv venv source .venv/bin/activate # Install in development mode uv pip install -e ".[dev]" # Run tests pytest # Rebuild index after making changes kicad-index ``` ## Requirements - Python 3.11+ - KiCad symbol libraries (`.kicad_sym` files) - Dependencies: `sexpdata`, `mcp` (installed automatically) ## How It Works 1. **Parsing**: The indexer uses `sexpdata` to parse KiCad's s-expression format 2. **Storage**: Components are stored in SQLite with FTS5 full-text search indexes 3. **Querying**: The MCP server receives requests via stdio and queries the database 4. **Response**: Results are returned in MCP-compliant JSON format ## License MIT ## Contributing Contributions welcome! Please open an issue or pull request. ## Acknowledgments - Built using [Anthropic's MCP SDK](https://github.com/anthropics/mcp) - Parses [KiCad](https://www.kicad.org/) symbol library format