KiCad MCP Server

# KiCad MCP Server - Development Log ## Project Summary Built an MCP server that provides searchable access to local KiCad symbol libraries. The server parses KiCad's `.kicad_sym` s-expression files, indexes them into a SQLite database, and exposes query tools via MCP. ## Architecture Two separate CLI tools: 1. **`kicad-index`** - Parses .kicad_sym files into SQLite database. Run once or when libraries change. 2. **`kicad-mcp`** - MCP server that queries the database. Runs as long-lived process launched by Claude Code. This separation keeps the server fast (no parsing on startup) and allows rebuilding the index independently. ## Project Structure ``` kicad_mcp/ ├── src/kicad_mcp/ │ ├── __init__.py # Package init, version │ ├── models.py # Component dataclass │ ├── parser.py # S-expression parsing with sexpdata │ ├── database.py # SQLite storage + FTS5 full-text search │ ├── indexer.py # CLI to build database │ └── server.py # MCP server with 4 tools ├── tests/ │ └── __init__.py ├── .venv/ # Local virtual environment (uv) ├── pyproject.toml # Package config (hatchling build) ├── CLAUDE.md # Project context for Claude └── SESSION_LOG.md # This file ``` ## Dependencies - `sexpdata>=1.0.0` - Parse KiCad s-expression format - `mcp>=1.0.0` - Anthropic's MCP Python SDK - `sqlite3` - Local database (stdlib) - Dev: `pytest`, `pytest-asyncio` ## Setup Commands ```bash # Create venv with uv (installed via: sudo pacman -S uv) uv venv # Install package in editable mode source .venv/bin/activate && uv pip install -e ".[dev]" # Build the component database (indexes /usr/share/kicad/symbols/) kicad-index # Check database stats kicad-index --stats ``` ## Database - Location: `~/.local/share/kicad-mcp/components.db` - Uses SQLite FTS5 for full-text search across name, description, keywords - Current index: **22,426 components** from system KiCad libraries ## MCP Tools Exposed | Tool | Description | |------|-------------| | `search_components` | Free-text search across name, description, keywords | | `list_component_types` | Get unique reference designators (R, C, U, etc.) | | `get_components_by_type` | Filter by reference type | | `get_component_details` | Full metadata for a specific component | ## Claude Code MCP Configuration Added via CLI command: ```bash claude mcp add --transport stdio kicad --scope user -- /home/cb/Projects/kicad_mcp/.venv/bin/kicad-mcp ``` This adds the server to `~/.claude.json` (user scope, available across all projects). Verify with: `claude mcp list` The full path to the venv script is used because the script has a shebang pointing to the venv's Python interpreter, so no activation is needed. Tools appear as: - `mcp__kicad__search_components` - `mcp__kicad__list_component_types` - `mcp__kicad__get_components_by_type` - `mcp__kicad__get_component_details` ## KiCad Symbol Format Reference Files are `.kicad_sym` using s-expression syntax: ```lisp (kicad_symbol_lib (version 20241209) (symbol "ComponentName" (property "Reference" "R") (property "Value" "Resistor") (property "Description" "Basic resistor") (property "ki_keywords" "resistor r element") (property "Datasheet" "~") (property "Footprint" "") ...visual data ignored... ) ) ``` Library locations on Linux: - System: `/usr/share/kicad/symbols/` - User: `~/.local/share/kicad/9.0/symbols/` ## Example Queries (tested working) ```python # Search search_components(conn, 'atmega', limit=3) # Returns ATmega microcontrollers with datasheets, footprints # Get types get_component_types(conn) # Returns ['#FLG', '#GND', '#PWR', 'A', 'AE', 'B', 'BT', 'C', ...] # By type get_components_by_type(conn, 'C', limit=5) # Returns capacitor components ``` ## Future Enhancements - Add footprint library support - Pagination for large result sets - More sophisticated search (fuzzy matching, filters) - Unit tests