KiCAD-MCP-Server

# KiCAD Library Integration

**Status:** ✅ COMPLETE
**Date:** 2026-09-01
**Version:** 2.7.0

## Overview

The KiCAD MCP Server includes full library integration for both footprints and symbols, enabling:

- ✅ Automatic discovery of all installed KiCAD footprint libraries
- ✅ Automatic discovery of KiCAD symbol libraries (including project-local)
- ✅ Search and browse footprints/symbols across all libraries
- ✅ Component placement using library footprints
- ✅ Symbol creation and editing with project-local library support (v2.2.2+)
- ✅ Library table maintenance: read, remove and repoint entries (v2.7.0)
- ✅ Structural validation of `.kicad_sym` files before KiCad refuses them (v2.7.0)
- ✅ Support for both `Library:Footprint` and `Footprint` formats

## How It Works

### Library Discovery

The library system automatically discovers both footprint and symbol libraries:

**Footprint Libraries** - `LibraryManager` class:

1. **Parsing fp-lib-table files:**
   - Global: `fp-lib-table` in the newest KiCad version's user config directory
     (`~/.config/kicad/10.0/` on Linux, `%APPDATA%\kicad\10.0\` on Windows,
     `~/Library/Preferences/kicad/10.0/` on macOS; then 9.0, then 8.0)
   - Project-specific: `project-dir/fp-lib-table`

**Symbol Libraries** - `DynamicSymbolLoader` class (v2.2.2+):

1. **Parsing sym-lib-table files:**
   - Global: `sym-lib-table` in the same directory as the global `fp-lib-table`
   - Project-local: `project-dir/sym-lib-table` (added v2.2.2)

2. **Resolving environment variables:**
   - `${KICAD9_FOOTPRINT_DIR}` → `/usr/share/kicad/footprints`
   - `${K IPRJMOD}` → project directory
   - Supports custom paths

3. **Indexing footprints:**
   - Scans `.kicad_mod` files in each library
   - Caches results for performance
   - Provides fast search capabilities

### Supported Formats

**Library:Footprint format (recommended):**

```json
{
  "componentId": "Resistor_SMD:R_0603_1608Metric"
}
```

**Footprint-only format (searches all libraries):**

```json
{
  "componentId": "R_0603_1608Metric"
}
```

## New MCP Tools

### 1. `list_libraries`

List all available footprint libraries.

**Parameters:** None

**Returns:**

```json
{
  "success": true,
  "libraries": ["Resistor_SMD", "Capacitor_SMD", "LED_SMD", ...],
  "count": 153
}
```

### 2. `search_footprints`

Search for footprints matching a pattern.

**Parameters:**

```json
{
  "pattern": "*0603*", // Supports wildcards
  "limit": 20 // Optional, default: 20
}
```

**Returns:**

```json
{
  "success": true,
  "footprints": [
    {
      "library": "Resistor_SMD",
      "footprint": "R_0603_1608Metric",
      "full_name": "Resistor_SMD:R_0603_1608Metric"
    },
    ...
  ]
}
```

### 3. `list_library_footprints`

List all footprints in a specific library.

**Parameters:**

```json
{
  "library": "Resistor_SMD"
}
```

**Returns:**

```json
{
  "success": true,
  "library": "Resistor_SMD",
  "footprints": ["R_0402_1005Metric", "R_0603_1608Metric", ...],
  "count": 120
}
```

### 4. `get_footprint_info`

Get detailed information about a specific footprint.

**Parameters:**

```json
{
  "footprint": "Resistor_SMD:R_0603_1608Metric"
}
```

**Returns:**

```json
{
  "success": true,
  "footprint_info": {
    "library": "Resistor_SMD",
    "footprint": "R_0603_1608Metric",
    "full_name": "Resistor_SMD:R_0603_1608Metric",
    "library_path": "/usr/share/kicad/footprints/Resistor_SMD.pretty"
  }
}
```

### 5. Library table maintenance (v2.7.0)

`register_symbol_library` and `register_footprint_library` add a row to a
`sym-lib-table` or `fp-lib-table`. These three tools cover the rest of the life
cycle, so cleaning up after a library move no longer means hand-editing the
table file.

All three take `scope` (`"project"` or `"global"`) or an explicit `tablePath`.
The two mutating tools accept `dryRun` to report the edit without performing it,
back the file up into a sibling `.mcp-backups/` directory, and re-parse the
result before writing. A rewrite that would leave the table unbalanced is
refused and the file is left untouched.

#### `list_library_table`

Read every registered library: nickname, type, URI and description.

It also resolves each URI through `${KIPRJMOD}`, KiCad's built-in library
directories, the path variables in `kicad_common.json`, and the environment,
then reports whether the file is actually present. This is what turns "ERC
reports hundreds of footprint link issues" into "this one row points at a
library that moved".

KiCad 10's `(type "Table")` rows are recognised as indirections rather than
libraries: the stock global table is a single row named `KiCad` standing for
200+ libraries, so the report says how many each row covers.

#### `remove_library_table_entry`

Unregister a library by nickname. Removing a `Table` row reports how many
libraries that unregisters.

#### `set_library_table_uri`

Repoint a library whose files moved, without touching any other row.

### 6. Symbol library maintenance (v2.7.0)

- `validate_symbol_library` - report the line and column of every structural
  fault in a `.kicad_sym`, instead of KiCad's bare "Unable to load library".
  Run it after any tool that edits a library.
- `set_symbol_pin_type` - set the electrical type of many pins at once, filtered
  by symbol, pin number, pin name or current type. Symbols imported from Eagle
  or SnapEDA often arrive with every pin `unspecified`, which buries real ERC
  errors. `dryRun` shows the affected pins first, and the library is written
  atomically with a timestamped backup.
- `find_duplicate_symbols` - group symbols that are the same part stored twice
  under different names, which is what happens when more than one source feeds a
  library. It counts placements per symbol across the project's sheets, so the
  report says which copy is safe to retire.

## Updated Component Placement

The `place_component` tool now uses the library system:

```json
{
  "componentId": "Resistor_SMD:R_0603_1608Metric", // Library:Footprint format
  "position": { "x": 50, "y": 40, "unit": "mm" },
  "reference": "R1",
  "value": "10k",
  "rotation": 0,
  "layer": "F.Cu"
}
```

**Features:**

- ✅ Automatic footprint discovery across all libraries
- ✅ Helpful error messages with suggestions
- ✅ Supports KiCAD 9.0 API (EDA_ANGLE, GetFPIDAsString)

## Example Usage (Claude Code)

**Search for a resistor footprint:**

```
User: "Find me a 0603 resistor footprint"

Claude: [uses search_footprints tool with pattern "*R_0603*"]
  Found: Resistor_SMD:R_0603_1608Metric
```

**Place a component:**

```
User: "Place a 10k 0603 resistor at 50,40mm"

Claude: [uses place_component with "Resistor_SMD:R_0603_1608Metric"]
  ✅ Placed R1: 10k at (50, 40) mm
```

**List available capacitors:**

```
User: "What capacitor footprints are available?"

Claude: [uses list_library_footprints with "Capacitor_SMD"]
  Found 103 capacitor footprints including:
  - C_0402_1005Metric
  - C_0603_1608Metric
  - C_0805_2012Metric
  ...
```

## Configuration

### Custom Library Paths

The system automatically detects KiCAD installations, but you can add custom libraries:

1. **Via KiCAD Preferences:**
   - Open KiCAD → Preferences → Manage Footprint Libraries
   - Add your custom library paths
   - The MCP server will automatically discover them

2. **Via Project fp-lib-table:**
   - Create `fp-lib-table` in your project directory
   - Follow the KiCAD S-expression format

### Supported Platforms

- ✅ **Linux:** `/usr/share/kicad/footprints`, `~/.config/kicad/<version>/`
- ✅ **Windows:** `C:/Program Files/KiCAD/*/share/kicad/footprints`
- ✅ **macOS:** `/Applications/KiCad/KiCad.app/Contents/SharedSupport/footprints`

## KiCAD 9.0 API Compatibility

The library integration includes full KiCAD 9.0 API support:

### Fixed API Changes:

1. ✅ `SetOrientation()` → now uses `EDA_ANGLE(degrees, DEGREES_T)`
2. ✅ `GetOrientation()` → returns `EDA_ANGLE`, call `.AsDegrees()`
3. ✅ `GetFootprintName()` → now `GetFPIDAsString()`

### Example Fixes:

**Old (KiCAD 8.0):**

```python
module.SetOrientation(90 * 10)  # Decidegrees
rotation = module.GetOrientation() / 10
```

**New (KiCAD 9.0):**

```python
angle = pcbnew.EDA_ANGLE(90, pcbnew.DEGREES_T)
module.SetOrientation(angle)
rotation = module.GetOrientation().AsDegrees()
```

## Implementation Details

### LibraryManager Class

**Location:** `python/commands/library.py`

**Key Methods:**

- `_load_libraries()` - Parse fp-lib-table files
- `_parse_fp_lib_table()` - S-expression parser
- `_resolve_uri()` - Handle environment variables
- `find_footprint()` - Locate footprint in libraries
- `search_footprints()` - Pattern-based search
- `list_footprints()` - List library contents

**Performance:**

- Libraries loaded once at startup
- Footprint lists cached on first access
- Fast search using Python regex
- Minimal memory footprint

### Integration Points

1. **KiCADInterface (`kicad_interface.py`):**
   - Creates `FootprintLibraryManager` on init
   - Passes to `ComponentCommands`
   - Routes library commands

2. **ComponentCommands (`component.py`):**
   - Uses `LibraryManager.find_footprint()`
   - Provides suggestions on errors
   - Supports both lookup formats

3. **MCP Tools (`src/tools/index.ts`):**
   - Exposes 4 new library tools
   - Fully typed TypeScript interfaces
   - Documented parameters

## Testing

**Test Coverage:**

- ✅ Library path discovery (Linux/Windows/macOS)
- ✅ fp-lib-table parsing
- ✅ Environment variable resolution
- ✅ Footprint search and lookup
- ✅ Component placement integration
- ✅ Error handling and suggestions

**Verified With:**

- KiCAD 9.0.5 on Ubuntu 24.04
- 153 standard libraries (8,000+ footprints)
- pcbnew Python API

## Known Limitations

1. **Library Updates:** Changes to fp-lib-table require server restart
2. **Custom Libraries:** Must be added via KiCAD preferences first
3. **Network Libraries:** GitHub-based libraries not yet supported
4. **Search Performance:** Linear search across all libraries (fast for <200 libs)

## Future Enhancements

- [ ] Watch fp-lib-table for changes (auto-reload)
- [ ] Support for GitHub library URLs
- [ ] Fuzzy search for typo tolerance
- [ ] Library metadata (descriptions, categories)
- [ ] Footprint previews (SVG/PNG generation)
- [ ] Most-used footprints caching

## Troubleshooting

### "No footprint libraries found"

**Cause:** fp-lib-table not found or empty

**Solution:**

1. Verify KiCAD is installed
2. Open KiCAD and ensure libraries are configured
3. Check that `fp-lib-table` exists in `~/.config/kicad/<version>/`
   (`%APPDATA%\kicad\<version>\` on Windows)

### "Footprint not found"

**Cause:** Footprint doesn't exist or library not loaded

**Solution:**

1. Use `search_footprints` to find similar footprints
2. Check library name is correct
3. Verify library is in fp-lib-table

### "Failed to load footprint"

**Cause:** Corrupt .kicad_mod file or permissions issue

**Solution:**

1. Check file permissions on library directories
2. Reinstall KiCAD libraries if corrupt
3. Check logs for detailed error

## Related Documentation

- [TOOL_INVENTORY.md](TOOL_INVENTORY.md) - generated catalogue of every tool
- [ROADMAP.md](ROADMAP.md) - planned work
- [STATUS_SUMMARY.md](STATUS_SUMMARY.md) - current implementation status
- [FOOTPRINT_SYMBOL_CREATOR_GUIDE.md](FOOTPRINT_SYMBOL_CREATOR_GUIDE.md) - creating custom parts
- [KiCAD Documentation](https://docs.kicad.org/9.0/en/pcbnew/pcbnew.html) - official KiCAD docs

## Changelog

**2026-08-20 - v2.7.0**

- ✅ `list_library_table`, `remove_library_table_entry`, `set_library_table_uri`
- ✅ `validate_symbol_library` reports the line and column of each fault
- ✅ `set_symbol_pin_type` for bulk pin electrical-type fixes
- ✅ `find_duplicate_symbols` for parts stored twice under different names
- ✅ `add_symbol_property` no longer drops a closing paren on every call
- ✅ Escaped quotes in property values survive a read/write round trip

**2026-03-21 - v2.2.3+**

- ✅ Project-local symbol library support (v2.2.2)
- ✅ Project-local footprint library support (v2.2.2)
- ✅ Implemented LibraryManager class
- ✅ Added 4 new MCP library tools
- ✅ Updated component placement to use libraries
- ✅ Fixed all KiCAD 9.0 API compatibility issues
- ✅ Tested end-to-end with real components
- ✅ Created comprehensive documentation

---

**Status: PRODUCTION READY** 🎉

The library integration is complete and fully functional. Component placement now works seamlessly with KiCAD's footprint libraries, enabling AI-driven PCB design with real, validated components.