{
  "markdown": "# MCP-KiCad\n\n**Design electronic schematics by talking to Claude.** This is an [MCP](https://modelcontextprotocol.io) server that lets a language model draw real KiCad schematics — placing parts, wiring nets, adding power symbols and running KiCad's own electrical rules check — and hand you a `.kicad_sch` file you can open, edit and manufacture from.\n\n*[Léeme en español](README.es.md)*\n\n<p align=\"center\">\n  <img src=\"docs/images/demo_buck_converter.svg\" alt=\"LM2596 buck converter schematic generated by MCP-KiCad\" width=\"620\">\n</p>\n\n<p align=\"center\"><em>An LM2596 step-down converter. Nobody drew this by hand: it was compiled from a text description, and it passes ERC.</em></p>\n\n---\n\n## What it actually does\n\nYou ask for a circuit in plain language. Claude writes a short declarative description of it and calls one tool, `compile_schematic`, which turns that description into a finished schematic file.\n\n> **You:** Build me a 555 astable running at about 1 Hz, 5 V supply.\n>\n> **Claude:** *[looks up the real pin names of the NE555, writes the design, compiles it]*\n> Done — 7 components, ERC clean. Here's the preview.\n\nThe result opens in KiCad like any other schematic. It is not a picture: it is a real file with a real netlist, ready for PCB layout.\n\n### What makes the output usable\n\nGenerating *something* is easy; generating a schematic a human would accept is not. Every compiled schematic is checked before you see it, and the compiler refuses to emit anything that fails:\n\n| Guarantee | How it is enforced |\n|---|---|\n| No wire crosses a wire from a different net | A geometric gate re-checks every segment. Offenders become net labels instead |\n| No wire runs through a component body | Same gate, checked against each symbol's real outline |\n| Every declared connection exists | The finished file is re-read and its netlist compared against what you asked for |\n| No accidental extra connections | The same check, in reverse — a wire that touches a pin it shouldn't is an error |\n| Power symbols really touch their pins | Verified by physical contact, not by net name |\n| A junction wherever wires meet | The rule was measured across the 115 schematics KiCad ships: a dot where three or more wire ends meet, and where two meet on a pin |\n| KiCad agrees | `kicad-cli` runs ERC on the result and the report comes back with it |\n\nIf a connection cannot be drawn cleanly, it degrades to a net label rather than producing a wire that lies. **The schematic is never silently wrong.**\n\nA net crossing *itself* is not one of those cases: it is one net either way, so the wire is cut at the crossing and given a junction rather than being thrown away. Only a genuine conflict with another net costs you a wire.\n\n### What it does not do\n\n- **No PCB work.** No board layout, no copper routing, no Gerbers. Schematics only, on purpose — a PCB from a bad schematic is worthless.\n- **No component invention.** It uses KiCad's installed symbol libraries, and `find_part` / `import_part` bring in what is missing from external KiCad libraries — verified before installation. If a part exists nowhere, it says so instead of drawing one.\n- **Not a simulator.** It draws what you describe; it does not tell you whether your circuit is a good idea.\n\n---\n\n## Requirements\n\n| | |\n|---|---|\n| **KiCad 10** | Provides `kicad-cli`, used for ERC and for rendering. Earlier versions are untested. |\n| **Claude Desktop** or **Claude Code** | Or any other MCP client. |\n| **Go 1.24+** | Only if you build from source. |\n\n---\n\n## Installation\n\n### Option A — one click (recommended)\n\nDownload **`mcp-kicad.mcpb`** from [**Releases**](https://github.com/unmateria/MCP-Kicad/releases/latest) and double-click it. Claude Desktop installs it as an extension: no JSON to edit, no paths to type. The bundle carries the Windows, macOS and Linux builds, so the same file works everywhere.\n\nThen skip straight to [Checking that it works](#checking-that-it-works).\n\n> On Apple Silicon the bundled macOS build runs through Rosetta. If you want the native one, take `mcp-kicad-darwin-arm64` from Option B instead.\n\n### Option B — download a binary\n\n1. Go to [**Releases**](https://github.com/unmateria/MCP-Kicad/releases) and download the file for your system:\n\n   | System | File |\n   |---|---|\n   | Windows (Intel/AMD) | `mcp-kicad-windows-amd64.exe` |\n   | Linux (Intel/AMD) | `mcp-kicad-linux-amd64` |\n   | Linux (ARM, e.g. Raspberry Pi) | `mcp-kicad-linux-arm64` |\n   | macOS (Apple Silicon) | `mcp-kicad-darwin-arm64` |\n   | macOS (Intel) | `mcp-kicad-darwin-amd64` |\n\n2. Put it wherever you like — say `C:\\Tools\\mcp-kicad.exe` or `~/bin/mcp-kicad`.\n\n3. On Linux and macOS, make it executable:\n\n   ```bash\n   chmod +x ~/bin/mcp-kicad\n   ```\n\n   On macOS the first run is blocked because the binary is unsigned. Allow it with:\n\n   ```bash\n   xattr -d com.apple.quarantine ~/bin/mcp-kicad\n   ```\n\nThere is nothing else to install. The binary is self-contained and needs no configuration file: it finds KiCad on its own.\n\n### Option C — build from source\n\n```bash\ngit clone https://github.com/unmateria/MCP-Kicad.git\ncd MCP-Kicad\ngo build -o mcp-kicad ./cmd/server      # add .exe on Windows\n```\n\n---\n\n## Connecting it to Claude\n\n*Not needed if you installed the `.mcpb` bundle — it registers itself.*\n\n### Claude Desktop\n\nEdit the configuration file — create it if it isn't there:\n\n| System | Location |\n|---|---|\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\nAdd the server:\n\n```json\n{\n  \"mcpServers\": {\n    \"kicad\": {\n      \"command\": \"C:\\\\Tools\\\\mcp-kicad.exe\",\n      \"args\": []\n    }\n  }\n}\n```\n\nOn Linux or macOS the command is a normal path, `\"/home/you/bin/mcp-kicad\"`.\n\n> **Windows note:** backslashes must be doubled in JSON (`C:\\\\Tools\\\\...`). A single backslash is the single most common reason the server fails to start.\n\n**Then quit Claude Desktop completely and reopen it.** Reloading the window is not enough — the server runs as a child process and only starts on a full restart.\n\n### Claude Code\n\n```bash\nclaude mcp add kicad -- /path/to/mcp-kicad\n```\n\n### Checking that it works\n\nAsk Claude:\n\n> Use get_project_info to check the KiCad setup.\n\nYou should get back the detected `kicad-cli` path, the library directories, and the output directory. If it reports that `kicad-cli` was not found, see [Configuration](#configuration) below.\n\n---\n\n## Using it\n\nJust describe the circuit. Be specific about what matters to you — supply voltage, part numbers you want, values you've already chosen — and leave the rest to Claude.\n\nPrompts that work well:\n\n> Design a 5 V regulated supply from a 12 V input using an LM7805, with input and output decoupling and a power LED.\n\n> Make me an ATmega328P minimal board: 16 MHz crystal with load caps, reset pull-up, ICSP header, and decoupling on both supply pins.\n\n> Build a two-transistor astable multivibrator that blinks two LEDs at roughly 2 Hz.\n\nUseful things to ask for afterwards:\n\n- *\"Show me the schematic\"* — renders a preview image.\n- *\"Export it as PDF\"* — through `kicad-cli`.\n- *\"Run ERC\"* — KiCad's electrical rules check, with the violations explained.\n- *\"Move the decoupling caps closer to U1 and recompile\"* — the design source is text, so revisions are cheap.\n\nThe generated files land in the output directory (`get_output_dir` tells you where; `set_output_dir` changes it).\n\n### The design source\n\nBehind the scenes, Claude writes a small JSON document and compiles it. You will rarely need to touch this, but it is worth seeing, because it explains why the results are stable — **positions are never given in millimetres, they are anchored pin-to-pin**:\n\n```json\n{\n  \"version\": 1,\n  \"project\": \"led_18650\",\n  \"sheet\": \"auto\",\n\n  \"blocks\": [\n    {\n      \"name\": \"led\",\n      \"symbols\": [\n        { \"ref\": \"BT1\", \"lib\": \"Device:Battery_Cell\", \"value\": \"18650\" },\n        { \"ref\": \"R1\", \"lib\": \"Device:R\", \"value\": \"100\", \"rot\": 90,\n          \"place\": { \"pin\": \"1\", \"at\": \"BT1.+\", \"dir\": \"up\", \"cells\": 1 } },\n        { \"ref\": \"D1\", \"lib\": \"Device:LED\", \"value\": \"LED_RED\", \"rot\": 90,\n          \"place\": { \"pin\": \"A\", \"at\": \"R1.2\", \"dir\": \"right\", \"cells\": 3 } }\n      ]\n    }\n  ],\n\n  \"nets\": {\n    \"VBAT\":   [\"BT1.+\", \"R1.1\"],\n    \"_ANODE\": [\"R1.2\", \"D1.A\"],\n    \"GND\":    [\"D1.K\", \"BT1.-\"]\n  },\n\n  \"power_nets\": { \"GND\": \"power:GND\" }\n}\n```\n\n<p align=\"center\">\n  <img src=\"docs/images/led_18650.svg\" alt=\"The schematic compiled from the source above\" width=\"260\">\n</p>\n\nThe first symbol in a block anchors it; every other symbol hangs off a pin of one already placed, a whole number of 2.54 mm grid cells away. That is how a schematic stays on-grid and readable no matter how the model reorders things.\n\nThe complete format is specified in [`internal/tools/design_format.md`](internal/tools/design_format.md) (the same text the `design_guide` tool serves to the model), and there are thirteen worked examples in [`docs/compiler/`](docs/compiler/) — from a two-part LED circuit to a greenhouse controller with 27 components.\n\n---\n\n## Configuration\n\nNone is required. The server looks for KiCad in the usual places:\n\n- **Windows** — `C:\\Program Files\\KiCad\\<version>\\bin\\kicad-cli.exe`, then `PATH`\n- **Linux** — `/usr/bin/kicad-cli`, `/usr/local/bin/kicad-cli`, then `PATH`\n- **macOS** — `/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli`, then `PATH`\n\nIf your install is somewhere unusual, or you want to change where files are written, copy `config.ini.example` to `config.ini` **next to the executable** and fill in what you need:\n\n```ini\n[paths]\nkicad_cli  = /opt/kicad/bin/kicad-cli\noutput_dir = /home/you/schematics\nlibs_root  = /home/you/mcp-kicad-libs\n\n[api_keys]\nmouser                =\ndigikey_client_id     =\ndigikey_client_secret =\n```\n\nThe API keys are optional and buy metadata only — no distributor serves CAD\nfiles. Every source that actually carries symbols and footprints needs no key.\n\nGenerated files default to `<your home>/mcp-kicad/output`.\n\n---\n\n## Tools\n\nThirty-three tools are exposed. In practice Claude drives almost everything through `compile_schematic`; the rest exist for inspection and for repairing an existing file.\n\n**Designing**\n`compile_schematic` · `design_guide` · `get_design_context` · `kicad_workflow_help` · `apply_template` · `list_templates`\n\n**Finding parts**\n`find_part` · `import_part` · `check_component_existence` · `symbol_pins` · `list_symbol_libraries` · `register_library`\n\n**Reading a schematic**\n`read_schematic` · `get_connectivity_summary` · `cluster_components` · `layout_metrics`\n\n**Editing by hand**\n`create_schematic` · `add_symbol` · `connect_pins` · `disconnect_pin` · `add_wire` · `add_label` · `add_power_rail` · `junction` · `no_connect` · `connect_netlist` · `batch_schematic`\n\n**Checking and exporting**\n`validate_design` (ERC/DRC) · `export_schematic_image` (SVG/PDF) · `modify_pcb_layout`\n\n**Setup**\n`get_project_info` · `get_output_dir` · `set_output_dir`\n\n---\n\n## Parts KiCad doesn't have\n\nKiCad ships around 22 700 symbols. The one you need is often not among them.\n`find_part` searches every source at once and `import_part` installs a\ncandidate:\n\n```\nfind_part   query=\"ESP32-C3-MINI-1\"\nimport_part ref=\"espressif:symbols/Espressif.kicad_sym#ESP32-C3-MINI-1\"\n→ MCP_Imported:ESP32-C3-MINI-1   53 pins, footprint matched, ready for compile_schematic\n```\n\n| Source | What it carries | Licence |\n|---|---|---|\n| *installed* | this machine's KiCad libraries and everything already imported | — |\n| **jlcpcb** | JLCPCB's assembly catalogue: symbol + footprint + 3D model, all matched | MIT |\n| **cern** | CERN Open Hardware: symbols for thousands of real part numbers | CERN-OHL-P-2.0 |\n| **digikey-lib** | Digi-Key's library, 150 category libraries | per repository |\n| **espressif** | Espressif's own ESP32 library | per repository |\n| **sparkfun** | SparkFun breakouts, sensors and connectors | CC-SA-4.0 |\n| **lcsc** | LCSC / EasyEDA, converted to KiCad — the long tail, by C-number | third-party data |\n| **mouser**, **digikey** | identification only: the real MPN, manufacturer, package and datasheet behind an order code. **No CAD files** — no distributor serves them. Needs an API key | — |\n\nEach source is indexed once into `libs/cache/` and searched offline from then\non. Nothing is installed until it has been verified:\n\n1. it parses,\n2. `kicad-cli` reads it back and rewrites it,\n3. it places in a scratch schematic with its pins resolved,\n4. its pins are compared against the footprint's pads,\n5. KiCad draws it, and you get the picture.\n\n**A part that fails is not installed at all.** A half-imported symbol is worse\nthan no symbol, because it looks like it works. And if a part exists in no\nsource, the answer is that it does not exist — never a substitute chosen\nquietly, never geometry drawn from imagination.\n\nEverything lands in one library, `MCP_Imported`, registered with KiCad so the\nGUI's symbol chooser sees it too. Each imported symbol carries an `MCP_Source`\nproperty recording where it came from, under what licence and when — which is\nwhy `libs/` is not versioned: it is reproducible from the sources.\n\n---\n\n## How it works\n\n`.design.json` → **compile** → `.kicad_sch`\n\n1. **Place.** Every symbol's position is derived from a pin anchor, resolved to absolute coordinates on the 2.54 mm grid.\n2. **Wire.** Short, obviously-correct connections are drawn with closed-form geometry; longer ones go to an A\\* router that avoids component bodies.\n3. **Power.** One power symbol per pin, offset in the direction the pin points, then aligned into rails.\n4. **Gate.** Every wire is re-examined. Anything that crosses another net, cuts through a symbol or overlaps collinearly is deleted and replaced by net labels — connectivity is preserved, the lie is not.\n5. **Tidy.** Reference and value text is moved off bodies and wires; the sheet is centred and the paper size upgraded if the circuit doesn't fit.\n6. **Verify.** The file is re-read from scratch, its netlist traced and compared against the source, and `kicad-cli` runs ERC.\n\nKiCad files are read and written through a real S-expression parser ([`internal/sexp`](internal/sexp)) — never by pattern-matching on text.\n\n---\n\n## Known limitations\n\n- **Text can still overlap on dense sheets.** Reference designators and net labels are moved to the lowest-overlap position available, but on a crowded schematic the best available spot sometimes still touches something. The compiler reports exactly what is left over and how much extra spacing would clear each one.\n- **Some connections become labels instead of wires.** This is the gate doing its job. Electrically identical, less pretty.\n- **PNG previews need a Chromium-family browser** (Edge, Chrome, Chromium or Brave). Without one, a lower-quality pure-Go renderer is used instead. Only the Windows path is verified in practice.\n- **Tested with Claude Desktop and Claude Code.** Other MCP clients should work but haven't been tried.\n\n---\n\n## Development\n\n```bash\ngo build -o mcp-kicad ./cmd/server   # build\ngo test ./...                        # all tests\ngo run ./cmd/verify_e2e              # end-to-end smoke test\ngo run ./cmd/compile -o out.kicad_sch docs/compiler/led_18650.design.json\ngo run ./cmd/measure_layout out.kicad_sch    # layout quality metrics\ngo run ./cmd/pininfo <library.kicad_sym>     # pin positions in a symbol library\n\n# The component sources are claims about the outside world. `go test ./...`\n# never touches the network; these re-measure them on demand.\nMCP_KICAD_LIVE=1 go test ./internal/parts/providers/ -run TestLive -v\nMCP_KICAD_LIVE=1 go test ./internal/tools/ -run TestLiveImportAndCompile -v\n```\n\nThe thirteen sources in `docs/compiler/` are the reference corpus — every change to the pipeline is checked against all of them.\n\nArchitecture notes live in [`CLAUDE.md`](CLAUDE.md).\n\n---\n\n## License\n\n[PolyForm Noncommercial License 1.0.0](LICENSE.md) — free to use, modify and share for any **noncommercial** purpose, including personal projects, hobby electronics, education, research and nonprofit organisations. Commercial use is not granted by this license.\n",
  "bytes": 16207,
  "sha": "c5d3258a903ba57ee0d4a31395ec695e6dbd5f8f7cef2cf07d213981fdc0e109",
  "repo_slug": "unmateria/mcp-kicad",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_unmateria_mcp_kicad_6f51a9d6/readme"
}