kicad-mcp-server/docs/LIBRARY_INTEGRATION.md

KiCAD Footprint Library Integration

Status: ✅ COMPLETE (Week 2 - Component Library Integration) Date: 2025-11-01 Version: 2.1.0-alpha

Overview

The KiCAD MCP Server now includes full footprint library integration, enabling:

• ✅ Automatic discovery of all installed KiCAD footprint libraries
• ✅ Search and browse footprints across all libraries
• ✅ Component placement using library footprints
• ✅ Support for both Library:Footprint and Footprint formats

How It Works

Library Discovery

The LibraryManager class automatically discovers footprint libraries by:

1. Parsing fp-lib-table files:

   • Global: ~/.config/kicad/9.0/fp-lib-table
   • Project-specific: project-dir/fp-lib-table

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

{
  "componentId": "Resistor_SMD:R_0603_1608Metric"
}

Footprint-only format (searches all libraries):

{
  "componentId": "R_0603_1608Metric"
}

New MCP Tools

1. list_libraries

List all available footprint libraries.

Parameters: None

Returns:

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

2. search_footprints

Search for footprints matching a pattern.

Parameters:

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

Returns:

{
  "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:

{
  "library": "Resistor_SMD"
}

Returns:

{
  "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:

{
  "footprint": "Resistor_SMD:R_0603_1608Metric"
}

Returns:

{
  "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"
  }
}

Updated Component Placement

The place_component tool now uses the library system:

{
  "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/9.0/
• ✅ 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):

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

New (KiCAD 9.0):

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 ~/.config/kicad/9.0/fp-lib-table exists

"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

• ROADMAP.md - Week 2 planning
• STATUS_SUMMARY.md - Current implementation status
• API.md - Full MCP API reference
• KiCAD Documentation - Official KiCAD docs

Changelog

2025-11-01 - v2.1.0-alpha

• ✅ 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.