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

# 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:

# 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:

claude mcp add --transport stdio kicad --scope user -- /path/to/kicad_mcp/.venv/bin/kicad-mcp

Or manually edit ~/.claude/claude_mcp_config.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

# 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
• Parses KiCad symbol library format