KiCad MCP Server

# KiCad MCP Server An MCP (Model Context Protocol) server that provides searchable access to local KiCad component symbol libraries. ## Architecture Two separate tools: 1. **Indexer** (`kicad-index`) - Parses .kicad_sym files into SQLite database. Run once or when libraries change. 2. **MCP Server** (`kicad-mcp`) - Serves queries from the database. Runs as long-lived MCP process. ## Project Structure ``` kicad_mcp/ ├── src/kicad_mcp/ │ ├── __init__.py │ ├── models.py # Component dataclass │ ├── parser.py # S-expression parser for .kicad_sym │ ├── database.py # SQLite storage and queries │ ├── indexer.py # CLI to build database │ └── server.py # MCP server implementation ├── tests/ ├── pyproject.toml └── CLAUDE.md ``` ## Commands ```bash # Install pip install -e . # Build the component database (run first) kicad-index # Index default locations kicad-index /path/to/symbols # Index specific directory kicad-index --stats # Show database stats # Run the MCP server kicad-mcp # Run tests pytest ``` ## Database Location Default: `~/.local/share/kicad-mcp/components.db` ## Dependencies - `sexpdata` - Parse KiCad s-expression format - `mcp` - Anthropic's MCP Python SDK - `sqlite3` - Local database (stdlib) ## KiCad Library Locations - System libraries: `/usr/share/kicad/symbols/` - User libraries: `~/.local/share/kicad/9.0/symbols/` ## KiCad Symbol Format Files are `.kicad_sym` using s-expression (lisp-like) 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" "") ... ) ) ``` Key properties to extract: - `Reference` - Designator prefix (R, C, U, etc.) - `Value` - Component value/name - `Description` - Human-readable description - `ki_keywords` - Space-separated search keywords - `Datasheet` - URL to datasheet - `Footprint` - Associated footprint Ignore visual/layout data (polylines, pins, etc.). ## MCP Tools | Tool | Description | |------|-------------| | `search_components` | Free-text search across name, description, keywords | | `list_component_types` | Get unique reference designators | | `get_components_by_type` | Filter by reference type (R, C, U) | | `get_component_details` | Full metadata for a specific component | ## Response Format ```json { "components": [ { "name": "Resistor", "library": "Device", "reference": "R", "value": "Resistor", "description": "Resistor", "keywords": "resistor r element", "datasheet": "~", "footprint": "" } ], "count": 1, "query": "resistor" } ``` ## Session Context For detailed development history and decisions, see `SESSION_LOG.md`. ## Local Development Uses `uv` for virtual environment management: ```bash # Setup (already done) uv venv source .venv/bin/activate && uv pip install -e ".[dev]" # Rebuild index source .venv/bin/activate && kicad-index ``` ## Claude Code MCP Config File: `~/.claude/claude_mcp_config.json` ```json { "mcpServers": { "kicad": { "command": "/path/to/kicad_mcp/.venv/bin/kicad-mcp", "args": [] } } } ``` Full path to venv script works because shebang points to venv Python—no activation needed.