KiCad MCP Server

# KiCad Library MCP Server Project Brief ## Project Overview Build an MCP (Model Context Protocol) server that allows Claude to query local KiCad component libraries. This server will parse KiCad's s-expression symbol format and expose searchable access to component metadata. ## Goals 1. Create a Python MCP server that connects to local KiCad symbol libraries 2. Parse `.kicad_sym` files (s-expression format) to extract component metadata 3. Expose query tools via MCP that allow Claude to search and filter components 4. Return structured, human-readable results This is an educational project to understand MCP architecture and s-expression parsing. ## Technical Context ### KiCad Library Format KiCad 9.0 uses s-expression format for symbol libraries. Key observations from exploration: - Files are lisp-like s-expressions (nested parenthetical structure) - File format: `(kicad_symbol_lib (version 20241209) ...)` - Each symbol is: `(symbol "ComponentName" ... )` - Important properties (extracted from nested `(property ...)` blocks): - `Reference` - designator prefix (e.g., "R", "C", "MES") - `Value` - component value or name - `Description` - human-readable description - `Datasheet` - URL to datasheet (if available) - `Footprint` - associated footprint name (if available) - `ki_keywords` - space-separated keywords for searching - Visual/layout data (polylines, etc.) can be ignored for now ### Library Location On Linux (Arch): - Installed via package: `/usr/share/kicad/symbols/` - User directory: `~/.local/share/kicad/9.0/symbols/` - Each directory contains multiple `.kicad_sym` files (Device, Connector, MCU_*, etc.) ### Example Symbol Structure ``` (symbol "Ammeter_AC" (property "Reference" "MES") (property "Value" "Ammeter_AC") (property "Footprint" "") (property "Datasheet" "~") (property "Description" "AC ammeter") (property "ki_keywords" "ammeter AC ampere meter") ...visual data... ) ``` ## MCP Server Design ### Tools to Expose 1. **search_components** - Free-text search across name, description, and keywords - Input: `query` (string), `limit` (optional, default 10) - Output: List of matching components with metadata 2. **list_component_types** - Get all unique reference designators (R, C, U, etc.) - Input: None - Output: List of designators 3. **get_components_by_type** - Filter by reference designator type - Input: `type` (string, e.g., "R" for resistors), `limit` (optional) - Output: Components of that type 4. **get_component_details** - Get full metadata for a specific component - Input: `component_name` (string) - Output: All available properties for that component ### Response Format All responses should return structured data: ```json { "components": [ { "name": "Resistor", "reference": "R", "description": "Resistor", "keywords": "resistor r element", "datasheet": "~", "footprint": "" } ], "count": 1, "query": "resistor" } ``` ## Implementation Phases ### Phase 1: Core Parser (Priority 1) - Parse s-expression files using `sexpdata` library - Extract symbol names and properties (description, keywords, datasheet, footprint, reference) - Load all symbols from a specified directory into an in-memory data structure - Handle multiple library files ### Phase 2: MCP Server (Priority 1) - Set up Python MCP server framework (using Anthropic's Python SDK) - Implement the four tools above with proper MCP tool definition - Handle tool invocation and return structured responses ### Phase 3: Search & Filtering (Priority 2) - Implement free-text search (substring matching or basic full-text) - Add case-insensitive filtering - Implement result limiting and pagination ### Phase 4: Testing & Polish (Priority 2) - Test with real KiCad libraries - Handle edge cases (missing properties, malformed files) - Add logging/debugging output - Create simple CLI for testing without MCP client ## Success Criteria 1. Server launches and connects as MCP server 2. Can query local KiCad symbol libraries from any library path 3. Returns accurate results for component searches 4. All four tools work and return properly formatted data 5. Can be called successfully from Claude Code ## Notes - Focus on symbol libraries first; footprint support can be added later - Don't worry about visual/rendering data in the s-expressions—skip it entirely - Keep the in-memory data structure simple (list of dicts or dataclass objects) - Don't optimize for performance yet; correctness first - Python stack: `sexpdata` for parsing, Anthropic SDK for MCP server ## Next Steps 1. Set up Python project structure and dependencies 2. Write symbol file parser using sexpdata 3. Implement basic MCP server skeleton 4. Implement tools one at a time, testing with real KiCad library files