kicad_footprint_library_mcp

# KiCad Library Generator — MCP Server > Generate production-ready KiCad 10 libraries (symbol + footprint + 3D model) for **any component** using AI. > Works with **Claude Desktop**, **ChatGPT**, and **Gemini**.  --- ## Why this exists Every PCB engineer knows the pain: the part you need isn't in KiCad's library. You either spend 2–3 hours building a footprint from scratch, or download one from Ultra Librarian / SnapMagic and hope the pad sizes are right. They often aren't. On a real RF module tested during development, Ultra Librarian's IPC-7351C estimate produced pads **28% smaller in area** than the manufacturer's own recommended land pattern in the datasheet. That's the difference between a reliable solder joint and a field failure. This tool was built after spending two weeks building KiCad 10 libraries the hard way — with Claude, datasheet pixel measurement, RF keepout validation, and round after round of DRC/ERC fixes. Every rule learned in that process is now hardcoded here so you never have to re-explain it to an AI again. --- ## Features ### Core differentiator — image-based pad measurement Reads pad dimensions from **datasheet land pattern figures as images** (pixel → mm), not from IPC-7351C text estimates. Every measurement is cross-checked against all numeric callouts in the drawing. ``` Ultra Librarian (IPC estimate): 0.559 × 2.007 mm ← wrong Manufacturer Fig (image): 0.600 × 2.400 mm ← correct Area difference: 28% ``` ### JLCPCB-first workflow Before generating anything, checks JLCPCB's database (~700k in-stock parts via [jlcsearch](https://jlcsearch.tscircuit.com)): - **Basic/Preferred part** with verified footprint → reuse it, save time - **Extended part** → download and verify pad sizes against datasheet - **Not in JLCPCB / RF module / custom land pattern** → generate from datasheet - Resolves LCSC 3D model download URLs automatically ### 24 MCP tools across 6 areas | Area | Tools | |---|---| | **Library generation** | `generate_full_library`, `generate_kicad_symbol`, `generate_kicad_footprint`, `generate_3d_model`, `package_kicad_library` | | **Measurement & lookup** | `measure_datasheet_drawing`, `get_component_info`, `get_available_packages` | | **JLCPCB integration** | `lookup_jlcpcb_part`, `find_jlcpcb_alternatives`, `get_jlcpcb_3d_model` | | **Validation** | `validate_kicad_library`, `check_schematic_erc`, `check_placement_clearance` | | **Advanced footprints** | `generate_thermal_pad_features`, `generate_multi_unit_symbol`, `calculate_ipc_pad_dimensions`, `get_ipc_footprint_name` | | **Production output** | `generate_bom`, `generate_cpl`, `add_supplier_properties`, `generate_accuracy_report`, `generate_power_symbols`, `generate_library_release` | ### Validation — 20 DRC + 12 ERC checks (IPC-7351C) **Footprint DRC (FP001–FP020):** courtyard present, courtyard encloses all pads, fab layer present, silkscreen clearance, pad overlap, IPC-2221 voltage clearance, THT annular ring (Class A/B/C), NPTH copper prohibition, thermal pad paste reduction, pin-1 marker, reference on silkscreen, value on fab, BGA NSMD pad sizing, RF keepout on `*.Cu`, keepout no fill block, model block multi-line, footprint in `.pretty` folder, SMD paste layer, pad number sequential, mounting hole NPTH. **Symbol ERC (SY001–SY012):** pin number uniqueness, footprint property prefix, power pins on active parts, unconnected power detection, GPIO as bidirectional, passive pin types, reference prefix correct, description present, datasheet URL present, no forbidden tokens, NC pins marked as `no_connect`, pin bijection to footprint. ### KiCad 10 rules hardcoded — 8 known bugs fixed | Bug | Fix | |---|---| | `(justify center)` invalid in `fp_text` | Omitted — centred text needs no justify field | | `generator_version` causes parse error | Never written | | Single-line model block silently fails | Multi-line template enforced | | `(fill ...)` in keepout causes DRC errors | Fill block never generated | | Footprint property missing library prefix | Format: `LibraryName:FootprintName` | | RF keepout on `F.Cu` only | Always written as `*.Cu` | | `inverted` pin type invalid | Remapped to `input` | | `not_connected` pin type invalid | Remapped to `no_connect` | ### Output goes to `~/Desktop/KiCad-Libraries` All generated files land on your Desktop — visible immediately. File contents are also returned inline in the AI response so you can inspect without opening a file manager. --- ## Supported component types Passives (0201–2512), ICs (QFN, QFP, SOP, DIP, LGA, BGA, WLCSP), MCUs, RF/WiFi/BT/Zigbee/Thread modules, connectors (USB-C, RJ45, JST, card edge), transistors (SOT23, TO252), diodes, crystals, op-amps (multi-unit), gate arrays, power modules, mounting holes, test points, fiducials. IPC land patterns built-in for 0201, 0402, 0603, 0805, 1206, 1210, 2010, 2512. 56 reference prefix rules (U, R, C, L, J, Q, D, Y, FB, F, RV, H, TP, SW, K, T…). 42-entry CPL rotation correction table for JLCPCB assembly. --- ## Supported AI clients | Client | Transport | How to use | |---|---|---| | **Claude Desktop** | stdio | `install/install.sh` configures automatically | | **ChatGPT** | HTTP | `python server.py --http` → point to `http://localhost:8000/mcp` | | **Gemini CLI** | HTTP | `python server.py --http` → `gemini --mcp http://localhost:8000/mcp` | | **Any MCP client** | stdio / HTTP | Same server, both transports | --- ## Quick start ### Requirements - Python 3.11 or 3.12 (3.13 works too) - Works with pyenv, conda, homebrew, system Python - KiCad 10 (for importing the generated libraries) ### Install — Mac / Linux ```bash git clone https://github.com/yourname/kicad-mcp-server.git cd kicad-mcp-server bash install/install.sh ``` The script: 1. Detects your Python automatically (resolves through pyenv → conda → homebrew → PATH) 2. Installs dependencies into that exact Python 3. Runs 80 validation tests 4. Writes `claude_desktop_config.json` with the correct absolute Python path Then **fully quit Claude Desktop (Cmd+Q on Mac)**, wait 5 seconds, reopen. ### Install — Windows ```powershell git clone https://github.com/yourname/kicad-mcp-server.git cd kicad-mcp-server powershell -ExecutionPolicy Bypass -File install\install.ps1 ``` ### Verify In Claude Desktop, ask: > *"How many KiCad tools do you have?"* Expected response: **24 tools**. ### Optional — 3D model generation (CadQuery) ```bash pip install cadquery ``` Without CadQuery, the server provides JLCPCB/LCSC model download URLs instead of generating STEP files. For most parts this is actually better (manufacturer model vs generated approximation). --- ## Usage examples ### Generate a library for any part ``` "Generate a KiCad 10 library for an RC0603FR-07100KL 10kΩ resistor. Check JLCPCB first." ``` The tool checks JLCPCB, finds it's a Basic part in 0603 package, suggests reusing their footprint, and generates the symbol with all supplier properties. ### Generate from a datasheet image ``` "Generate a KiCad 10 footprint for this RF module. I'll upload the land pattern figure — use pixel measurement for pad sizes." ``` Upload Fig 8.3 from the datasheet. The tool measures pixel coordinates, converts to mm, cross-checks against all callouts, applies RF keepout rules, and generates a verified footprint. ### Generate a complete library from scratch ``` "Generate a complete KiCad 10 library for an STM32F103C8T6. JLCPCB part C8734. Package: LQFP48." ``` Returns: `.kicad_sym` + `.kicad_mod` in `.pretty` folder + STEP 3D model URL + BOM CSV + CPL CSV with rotation correction + accuracy report + import instructions. ### Find a cheaper JLCPCB alternative ``` "Find a Basic JLCPCB alternative to my AMS1117-3.3 SOT223 LDO." ``` Searches for Basic/Preferred parts with the same package, sorted by stock, with reuse suggestion for each. --- ## Project structure ``` kicad-mcp-server/ ├── server.py # MCP server — 24 tools, single stdio entry point ├── requirements.txt ├── README.md │ ├── tools/ # One file per feature area │ ├── symbol_gen.py # .kicad_sym generation │ ├── footprint_gen.py # .kicad_mod + keepout + model block │ ├── model_gen.py # CadQuery STEP generation │ ├── validator.py # kiutils DRC/ERC validation │ ├── image_measure.py # Pixel → mm from datasheet figures │ ├── component_lookup.py # Part number → component data │ ├── jlcpcb_lookup.py # JLCPCB/LCSC API + reuse decision │ ├── bom_cpl.py # BOM CSV, CPL CSV, rotation correction │ ├── thermal_pad.py # Paste web + via array for QFN/LGA │ ├── multi_unit_symbol.py # Multi-unit symbols (op-amps, gates) │ ├── ipc_land_pattern.py # IPC-7351C Class A/B/C pad calculator │ ├── erc_checks.py # Pin conflict, PWR_FLAG, net tie │ ├── accuracy_report.py # Markdown sign-off report + library diff │ ├── library_metadata.py # IPC naming, versioning, review checklist │ └── packager.py # ZIP with .pretty folder + README │ ├── rules/ # All rules as Python constants │ ├── kicad10_rules.py # KiCad 10 syntax rules, known bugs, 3D conventions │ └── ipc_rules.py # IPC-7351C DRC/ERC checks, pad shapes, courtyard │ ├── tests/ │ └── test_rules.py # 80 tests — run fully offline │ └── install/ ├── install.sh # Mac/Linux installer (handles pyenv/conda/homebrew) ├── install.ps1 # Windows PowerShell installer ├── start_server.py # Bootstrap for .mcpb (venv + dep install) └── manifest.json # Claude Desktop Extension manifest ``` --- ## Importing into KiCad 10 After the tool generates a library: **Symbol:** `Preferences → Manage Symbol Libraries → Add Existing → select .kicad_sym file` **Footprint:** `Preferences → Manage Footprint Libraries → Add Existing → select .pretty FOLDER` ⚠️ Select the **folder** (`LibraryName.pretty`), not an individual `.kicad_mod` file. **3D model:** Place the `.step` file at the path shown in the footprint's model property, or set the `KICAD6_3DMODEL_DIR` environment variable. --- ## JLCPCB assembly workflow 1. Generate library → `generate_full_library` with your LCSC part number 2. Check the JLCPCB reuse suggestion and evidence 3. Generate BOM → `generate_bom` with LCSC numbers for all parts 4. Generate CPL → `generate_cpl` (rotation corrections applied automatically) 5. Upload Gerbers + BOM + CPL to JLCPCB 6. **Visually verify pin-1 orientation** in the JLCPCB assembly preview before confirming Step 6 cannot be automated — it's a 30-second visual check that catches any remaining rotation offset. --- ## Dependencies | Package | Purpose | Required | |---|---|---| | `mcp>=1.0.0` | MCP protocol (FastMCP) | Yes | | `kiutils>=0.4.0` | KiCad file parser — same one KiCad uses | Yes | | `pdfplumber>=0.9.0` | PDF datasheet text extraction | Yes | | `pytest>=7.0.0` | Test runner | Dev | | `cadquery` | STEP 3D model generation | Optional | --- ## Running tests ```bash python3 -m pytest tests/test_rules.py -v ``` 80 tests, all offline. Covers every KiCad 10 bug, IPC rule, JLCPCB decision, and component classification. Tests pass on Python 3.11, 3.12, 3.13. --- ## Troubleshooting | Problem | Fix | |---|---| | "Could not attach to MCP server" | Re-run `bash install/install.sh` — rewrites config with correct Python path | | "Uvicorn running on 8000" in terminal | Old server.py with duplicate `__main__` block — replace with latest | | No tools after restart | Fully quit Claude Desktop (Cmd+Q), not just close the window | | `FastMCP() got unexpected keyword argument 'version'` | Old server.py — replace with latest (removed `version=` and `description=` kwargs) | | pyenv / conda Python not found | Run `bash install/install.sh` — detects real binary automatically | | Tests fail | `python3 -m pip install -r requirements.txt` then retry | | Output files not visible | Check `~/Desktop/KiCad-Libraries/` | --- ## Background This project grew out of building custom KiCad 10 libraries for a real PCB design — RF modules, custom connectors, and ICs not covered by the standard KiCad library. Working through the process with Claude revealed dozens of repeatable rules: how to read land patterns from datasheet images, how to apply RF keepout zones correctly, which KiCad 10 syntax bugs cause silent failures, and how to validate everything with kiutils. Rather than re-explaining those rules every time, they are now hardcoded in this MCP server. Every rule, every fix, every validation check was learned from a real design session. --- ## Roadmap - [ ] Publish to PyPI (`uvx kicad-library-generator` one-liner install) - [ ] KiCad Plugin Manager integration (run inside KiCad directly) - [ ] Expand known component database with more verified datasheet entries - [ ] JLCPCB rotation correction auto-detection from part preview - [ ] Multi-page datasheet navigation for components with complex land patterns --- ## License MIT — see [LICENSE](LICENSE) --- ## Contributing PRs welcome, especially: - New entries in `tools/component_lookup.py` `KNOWN_COMPONENTS` dict (verified datasheet values) - New JLCPCB CPL rotation corrections in `tools/bom_cpl.py` `JLCPCB_ROTATION_CORRECTION` - Additional KiCad 10 syntax bug fixes in `rules/kicad10_rules.py` For each new component entry, include the datasheet figure reference, measured pad dimensions, and callout cross-check.