Skip to content
Back to search

KiCAD-MCP-Server

KiCAD MCP is a Model Context Protocol (MCP) implementation that enables Large Language Models (LLMs) like Claude to directly interact with KiCAD for printed circuit board design.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/mixelpixx/KiCAD-MCP-Server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/mixelpixx/KiCAD-MCP-Server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mixelpixx--kicad-mcp-server/badge.svg)](/listings/mixelpixx--kicad-mcp-server)

HTML

<a href="/listings/mixelpixx--kicad-mcp-server"><img src="/api/listings/mixelpixx--kicad-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

- The install instructions now clone the `stable` branch, which holds the latest release. `main` may carry fixes that are not released yet.

Full details in the [CHANGELOG](CHANGELOG.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 2,128 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # KiCAD MCP Server
  2. A Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with KiCAD for PCB design automation. Built on the MCP 2025-06-18 specification, this server provides comprehensive tool schemas and real-time project state access for intelligent PCB design workflows.
  3. **Open source (MIT) and actively maintained.** New releases keep coming, and bug
  4. reports, pull requests and [discussion](https://github.com/mixelpixx/KiCAD-MCP-Server/discussions)
  5. are welcome here.
  6. > ## Konnect is now Konnect-EDA, at Orchis.ai
  7. >
  8. > **[Konnect-EDA](https://github.com/Orchis-ai-LLC/Konnect-EDA)** grew out of this
  9. > project. It is a native KiCad 10 plugin: a single Rust binary that works through
  10. > KiCad's official IPC API and `kicad-cli`, with no SWIG. Its 228 tools, in 21
  11. > on-demand toolsets, cover schematic capture, PCB layout and routing, ERC and DRC,
  12. > design-review audits, JLCPCB parts and fab outputs, with bundled skills for Claude
  13. > and Codex.
  14. >
  15. > - **Free for students, hobbyists and individual developers, now and after 1.0.**
  16. > Everyone can use it free during the beta. From 1.0, personal, hobby, student and
  17. > individual developer use stays free, with a free license key. Only businesses need
  18. > a commercial license. See [licensing](https://konnect-eda.orchis.ai/licensing/).
  19. > - **Get it:** install guide and downloads on [GitHub](https://github.com/Orchis-ai-LLC/Konnect-EDA),
  20. > and more at [konnect-eda.orchis.ai](https://konnect-eda.orchis.ai).
  21. > - **Runs on your machine.** It sends nothing to Orchis.ai. See
  22. > [what leaves your machine](https://konnect-eda.orchis.ai/#leaves).
  23. > - **Help build it:** report bugs and request features in
  24. > [its issues](https://github.com/Orchis-ai-LLC/Konnect-EDA/issues). Code
  25. > contributors can [sign up here](https://orchis.ai/konnect/join).
  26. >
  27. > The earlier `mixelpixx/Konnect` repository is archived. Konnect-EDA replaces it.
  28. | | KiCAD MCP Server (this repository) | Konnect-EDA |
  29. | -------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
  30. | License | MIT, open source | Closed source. Free for students, hobbyists and individual developers; businesses need a license from 1.0 |
  31. | KiCad versions | 9 and 10 | 10 |
  32. | Runs as | Python and TypeScript MCP server | Native KiCad plugin, a single Rust binary |
  33. | Works through | KiCad's Python API (SWIG), with an experimental IPC backend | KiCad's IPC API and `kicad-cli` |
  34. | Home | Here | [Orchis-ai-LLC/Konnect-EDA](https://github.com/Orchis-ai-LLC/Konnect-EDA) · [konnect-eda.orchis.ai](https://konnect-eda.orchis.ai) |
  35. ## Overview
  36. The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard from Anthropic that allows AI assistants to securely connect to external tools and data sources. This implementation provides a standardized bridge between AI assistants and KiCAD, enabling natural language control of PCB design operations.
  37. **Key Capabilities:**
  38. - 257 tools registered, every one of them indexed for keyword discovery
  39. - 257 tools across 20 categories with JSON Schema validation
  40. - Keyword tool discovery via `search_tools` / `get_category_tools`
  41. - Optional toolboxes: start with a 37-tool core and open the rest by category,
  42. to save context and stay under client tool limits
  43. - 23 dynamic resources exposing project state
  44. - Complete schematic workflow with 65 tools (authoring, batch edits, hierarchy, layout) and dynamic symbol loading (~10,000 symbols)
  45. - Freerouting autorouter integration (Java, Docker, or Podman)
  46. - Custom footprint and symbol creation tools
  47. - JLCPCB parts integration with 2.5M+ component catalog and local library search
  48. - Datasheet enrichment via LCSC
  49. - Full MCP 2025-06-18 protocol compliance
  50. - Cross-platform support (Linux, Windows, macOS)
  51. - Real-time KiCAD UI integration via IPC API (experimental)
  52. - Comprehensive error handling and logging
  53. ## Try out Arduino MCP - now you can get Claude to help in the IDE, real time!:
  54. https://github.com/mixelpixx/arduino-ide
  55. ## What's New in v2.9.0
  56. Board inspection tools, operating modes, autorouting by layer and by net, and
  57. a large batch of fixes, most of them found on real boards. Thanks to
  58. @dp-web4, @karu2003, @rmskkn, @YORROY123, @0anes0, @vim4all,
  59. @AlexanderSaydakov, @TimChild, @zjywlive and @b0gdaniy.
  60. ### New tools
  61. - `get_stackup` reads the stackup from the board file and can check it against
  62. a recipe; `set_stackup_layer` sets one row's thickness and dielectric
  63. properties (@karu2003).
  64. - `summarize_vias` and `summarize_net_copper` count a net's or a board's
  65. copper without listing thousands of items (@karu2003).
  66. - `audit_via_nets` compares every via's net with a reference board or a git
  67. revision. KiCad can move a via onto another net when it saves, and DRC does
  68. not notice (@dp-web4).
  69. - `set_voltage_clearance_rules` writes clearance and creepage rules graded by
  70. the working voltage between net classes, from a spacing table you supply
  71. (@dp-web4).
  72. - `get_component_list` filters by region (@karu2003). Two new prompts guide a
  73. DC power-distribution review and a shield review (@karu2003).
  74. ### Operating modes
  75. - `KICAD_MCP_OPERATING_MODE=readonly` leaves only the tools that cannot change
  76. the design, for review agents. `manufacturing` adds the export tools. Unset,
  77. nothing changes. The idea is from @b0gdaniy.
  78. ### Autorouting
  79. - `signalLayers` keeps tracks off plane layers, and `layerTraceCosts` makes a
  80. layer expensive rather than forbidden (@dp-web4).
  81. - `routeNets` and `excludeNets` route one set of nets and keep the rest as
  82. they are, so a board can be routed one domain at a time (@dp-web4).
  83. - Every outline of a keepout rule area reaches Freerouting (@dp-web4).
  84. ### Fixes
  85. - `sync_schematic_to_board` takes nets, symbol links and fields from KiCad's
  86. own netlist. On a real 333-pad board, 304 pads had the wrong net before
  87. (@dp-web4).
  88. - Saves are no longer refused as "changed externally" after
  89. `sync_schematic_to_board` (@vim4all), `autoroute`, `import_ses` or
  90. `refill_zones`.
  91. - Schematic edits are refused while the schematic is open in KiCad, which
  92. would otherwise overwrite them (@0anes0).
  93. - Library listing and search find KiCad's tables under `KICAD_CONFIG_HOME` and
  94. on a fresh install. One behaviour change: the symbol loader now reads only
  95. the newest KiCad version's global table, as KiCad does (@dp-web4).
  96. - `add_via` keeps its net inside another net's zone and reads the parameters
  97. its schema declares; `modify_trace` works on the IPC backend; STM32 symbols
  98. load again; `search_footprints` with `library` finds late libraries
  99. (@dp-web4, @YORROY123, @rmskkn, @zjywlive).
  100. - `run_drc` reports unconnected items and schematic parity, board tools keep
  101. working after an image render, and project libraries survive a move
  102. (@dp-web4, @AlexanderSaydakov).
  103. Full details in the [CHANGELOG](CHANGELOG.md).
  104. ## What's New in v2.8.3
  105. Toolboxes to keep the tool list small, a Linux setup script, and a batch of
  106. fixes. Thanks to @cornellana, @YORROY123, @reinauer and @ToThePointTechDev.
  107. ### Toolboxes
  108. - Set `KICAD_MCP_TOOLBOXES=core` and a client starts with 37 tools instead of
  109. about 250: the core tools, `search_tools`, and `list_toolboxes`,
  110. `open_toolbox` and `close_toolbox`. The assistant opens the toolboxes a task
  111. needs. Name toolboxes in the setting, such as `schematic,drc`, to have them
  112. open from the start; Claude Desktop needs that, because it doesn't re-read
  113. the tool list until it restarts. Without the setting nothing changes. See
  114. [Toolboxes](#toolboxes).
  115. - Every tool now has a category, so `search_tools` finds all of them (#345).
  116. ### Setup
  117. - `setup-linux.sh` detects KiCad's Python, checks the dependencies in the
  118. environment it will configure, and merges the server into Claude Desktop's
  119. config with a backup, like `setup-macos.sh` (#445, @reinauer).
  120. ### Fixes
  121. - `export_gerber` writes the files it reports. On the SWIG backend it wrote
  122. none while listing every layer (#455, #456, @cornellana).
  123. - `download_jlcpcb_database` gets the time a download needs, reports the real
  124. error when it fails, and no longer mixes cached yaqwsx volumes from different
  125. days (#454).
  126. - A tool call made while the server is still starting waits instead of failing
  127. with "Python process ... is not running" (#453).
  128. - Courtyard checks test each outline of a multi-outline courtyard separately
  129. (#406, #452, @YORROY123).
  130. - `route_differential_pair` reads the parameters its schema declares, and
  131. `gap` is the edge-to-edge spacing; `get_nets_list` returns the statistics it
  132. advertises, and `get_net_pads` honours `unit` (#450, #451, @YORROY123).
  133. - MCP SDK 1.31.0 (from 1.29.0).
  134. Full details in the [CHANGELOG](CHANGELOG.md).
  135. ## What's New in v2.8.2
  136. A patch release with three fixes. KiCad 10's stock libraries are found on
  137. installs where the global library table refers to them through a variable. New
  138. sheets are written the way KiCad writes them. A line break in a value no longer
  139. makes KiCad drop a sheet. Thanks to @zerthimon, who reported and fixed the
  140. first two and traced the third.
  141. ### KiCad 10's stock libraries
  142. - KiCad 10's global library tables hold one row that points to KiCad's own
  143. table of stock libraries. Where that row uses `${KICAD10_TEMPLATE_DIR}`, as
  144. on Linux, the server found none of them: `search_symbols` came back empty and
  145. `list_library_symbols` failed for `Device`. The row is now followed, so all
  146. 223 symbol and 155 footprint libraries are found (#438, #439).
  147. - Loading a library table went from about half a second to a few milliseconds,
  148. because path variables are now resolved once per table instead of once per
  149. row.
  150. ### Hierarchical sheets
  151. - `add_hierarchical_sheet` writes a sheet the way KiCad does. It uses the
  152. `Sheetname` and `Sheetfile` property names, and puts the page number inside
  153. the sheet block, once for each use of the parent sheet. KiCad 10 flagged the
  154. old format when the project was opened (#436, #437).
  155. - Page numbers are unique across the project, and adding a sheet inside a
  156. sub-sheet no longer fails.
  157. ### Line breaks in values
  158. - A multi-line value, such as a Description set with
  159. `edit_schematic_component`, was written with a raw line break that KiCad
  160. cannot read. In a sub-sheet, KiCad then left the whole sheet out of the
  161. design without an error. On KiCad's complex_hierarchy demo, one such value
  162. took the netlist from 68 components to 10. Line breaks are now written the
  163. way KiCad writes them (#441).
  164. - `get_schematic_component` returns fields whose values contain quotes, such
  165. as the Description of KiCad's stock GND symbol. Before, those fields were
  166. missing from its result.
  167. ### Installing
  168. - The install instructions now clone the `stable` branch, which holds the
  169. latest release. `main` may carry fixes that are not released yet.
  170. Full details in the [CHANGELOG](CHANGELOG.md).
  171. ## What's New in v2.8.1
  172. A patch release with three fixes for hierarchical schematics and KiCad
  173. 10-only machines. They came out of reviewing the fixes that went into v2.8.0.
  174. ### Parts on reused sheets get a reference per use
  175. - A sheet placed more than once gets an instance entry, with its own
  176. reference, for every use. KiCad's complex_hierarchy demo uses one amplifier
  177. sheet twice. Before, a part placed there had one entry, and kicad-cli listed
  178. it twice with "schematic has annotation errors" (#428).
  179. - `annotate_schematic` numbers each use on its own and skips numbers already
  180. used on other sheets of the project. It keeps the units of a multi-unit part
  181. on one number and gives power symbols KiCad's leading zero (#432).
  182. - `add_schematic_component`, `batch_add_components` and `annotate_schematic`
  183. report the reference in each use, so callers don't give those numbers to
  184. other parts.
  185. - Sheets kept in a subdirectory now find their root, as in KiCad's
  186. royalblue54L_feather demo, which keeps its sheets in `sch/`.
  187. `add_hierarchical_sheet` writes correct paths at any depth (#428).
  188. ### KiCad 10-only machines
  189. - Global library registration writes the newest KiCad version's table. It used
  190. to create a 9.0 table that KiCad 10 never reads. With no global table yet it
  191. now returns an error, because creating one would hide KiCad's stock libraries
  192. (#425).
  193. - `${KICAD10_3RD_PARTY}` (Plugin and Content Manager libraries) resolves at its
  194. default location. The cairo DLL is now found in KiCad 10 installs and custom
  195. install folders (#425).
  196. Full details in the [CHANGELOG](CHANGELOG.md).
  197. ## What's New in v2.8.0
  198. ### A crashed or stuck worker comes back on its own
  199. One bad request could end the Python worker, and a command that hung inside
  200. pcbnew blocked every call queued behind it. Either way, every later tool call
  201. failed until the MCP server was restarted by hand. Now a request whose response
  202. cannot be sent gets an error instead of ending the worker (#405), and the
  203. bridge restarts a worker that exits or wedges, failing only the call in flight
  204. (#390, @siddolo). A worker that keeps crashing stays down after three restarts
  205. in five minutes instead of respawning forever. On Windows, a log file locked by
  206. another program no longer silences logging, and a missing kicad-skip now
  207. disables only the schematic tools that need it (#389, @AmirF194).
  208. ### Schematic edits land where KiCad expects them
  209. - Parts placed on a sub-sheet get the hierarchical instance path KiCad writes
  210. (#423, @zerthimon).
  211. - `connect_to_net` no longer puts a label where a moved part's pin used to be
  212. (#427).
  213. - `add_schematic_wire` reports an endpoint that did not snap to a pin instead
  214. of calling a floating wire a success (#404, reported by @andersresen).
  215. - One unit of a multi-unit part can be moved, rotated or deleted on its own,
  216. dragging keeps wiring orthogonal and carries no-connect flags along, net
  217. labels face the way their pin does, and placed symbols keep the library's
  218. field visibility (#391, @komar3456).
  219. - `edit_component` really swaps the footprint, keeping nets, the schematic
  220. link, attributes and the lock (#411, @AmirF194).
  221. - `sync_schematic_to_board` reads only the design's own sheets and keeps
  222. unlabeled nets (#400, #402), and placing a symbol no longer writes KiCad
  223. 10-only attributes into KiCad 8 or 9 schematics (#351).
  224. ### GUI driver, opt-in
  225. Eleven tools drive KiCad's live GUI: menus, toolbars, dialogs and
  226. action-plugin buttons (#333, @rossvonfange). Nothing is installed until you run
  227. `install_gui_driver`, and the helper listens only when
  228. `KICAD_GUI_DRIVER_ENABLE=1` is set, on 127.0.0.1, with a per-session token.
  229. ### KiCad 10, IPC and Freerouting
  230. - IPC placement on KiCad 10 places the real library footprint again (#378,
  231. @AlloyPlane), and IPC rotation keeps 3D models (#422, @Putpluto).
  232. - KiCad 10 and custom install folders are found on Windows (#416,
  233. @DieterMayerOSS; setup scripts: #356, @LiJoeAllen), and a KiCad started from
  234. `PATH` is detected on Linux (#401, @famez).
  235. - The `PCB_VIA::GetWidth` assert dialog on KiCad 9 and 10 is gone, and KiCad 8
  236. works again (#398, @scorp508).
  237. - `autoroute` and `import_ses` report a failed import instead of success, the
  238. Java version is read from the Freerouting JAR, and routed tracks keep the
  239. edge clearance around mounting holes (#417, #418, #419, @outstanda).
  240. ### Faster net listing
  241. `list_schematic_nets` and `generate_netlist` resolve every net in one pass per
  242. sheet: about ten times faster on KiCad's demo projects, with identical results
  243. (#394, @markszente).
  244. ### New tools
  245. - **GUI driver**: the eleven tools above.
  246. - **Digi-Key**: `digikey_search_parts`, `digikey_check_library_availability`,
  247. `digikey_test_connection` (#368, @karu2003).
  248. - **`set_net_color`** (#375, @JMcordobamendez).
  249. `search_tools` now indexes 184 of the 244 registered tools, in 17 categories.
  250. Full details in the [CHANGELOG](CHANGELOG.md).
  251. ## What's New in v2.7.0
  252. ### The bridge no longer crosses its wires
  253. The Node-Python protocol had no request IDs: after one timeout, the next
  254. command was silently resolved with the _previous_ command's late result, and
  255. every response after that was off by one. Tool calls now carry an ID that
  256. Python echoes back; stale responses are discarded instead of mis-delivered
  257. (#373). The MCP transport also connects before Python spawns, so clients no
  258. longer stack up against a silent server for up to two minutes during pcbnew
  259. warm-up (#377).
  260. ### Two file-corruption classes fixed
  261. `add_symbol_property` dropped a closing paren on every call and could splice
  262. a unit symbol into a top-level sibling (#362, @karu2003). And S-expression
  263. escaping is now symmetric: reads (#336) and writes (#324) share one
  264. escape-aware implementation, so a property value containing `\"` survives a
  265. round-trip — 419 of KiCad's own stock symbol files carry such values.
  266. ### 8 new tools
  267. - **Validation**: `validate_schematic`, `validate_symbol_library` — locate
  268. structural damage with line/column, confirmed via `kicad-cli` on a copy.
  269. - **Library tables**: `list_library_table`, `remove_library_table_entry`,
  270. `set_library_table_uri` — the missing CRUD around `register_*_library`.
  271. - **Symbol editing**: `set_symbol_pin_type` (bulk pin type fixes with
  272. dry-run), `find_duplicate_symbols` (the same part stored twice).
  273. - **Back-annotation**: `backannotate_footprints` — PCB footprint choices
  274. flow back to the schematic, the reverse of `sync_schematic_to_board`.
  275. All by @karu2003. With #359 (@AmirF194) registering 15 existing symbol tools,
  276. `search_tools` now indexes 169 tools in 15 categories.
  277. ### Quality of life
  278. - `autoroute` stages its `.dsn`/`.ses` work files in a temp directory and
  279. cleans up on every exit — no more litter next to your board, no stale-SES
  280. imports, and a killed run says "terminated externally" instead of
  281. `exit code 4294967295` (#249, scoped by @Dewieinns' traces).
  282. - Placed symbols inherit the library's default Footprint (#300,
  283. implementation by @stefangordon).
  284. - `add_layer` actually adds inner copper layers (#222) — it previously wrote
  285. to non-copper layer IDs and renamed F.SilkS.
  286. - `sync_schematic_to_board` matches by symbol UUID, not just refdes (#250).
  287. - JLCPCB tools decode the new upstream `source-db-v2` schema (#352,
  288. @stefanobaldo) and degrade gracefully when the parts DB is unavailable
  289. (#264, @fage2022).
  290. - `setup-macos.sh --verify` now fails when Python requirements are missing
  291. instead of passing on a server that cannot start (#350, @francisrath).
  292. Full details in the [CHANGELOG](CHANGELOG.md).
  293. ## What's New in v2.6.0
  294. ### A session-killing bug is fixed
  295. Deleting anything from a board — a component, a trace, a board outline —
  296. worked exactly once. The next operation, even a pure read, failed with a
  297. `SwigPyObject` error, and only `close_project` then `open_project` recovered.
  298. `BOARD.Remove()` hands C++ ownership to Python, so dropping the reference ran
  299. a destructor on an object KiCad still pointed at, corrupting SWIG state
  300. process-wide. Six call sites were affected; all now use `BOARD.Delete()`.
  301. ### 10 new tools
  302. - **Vendor PCB import**: `import_pcb` converts PADS, Altium, Eagle, CADSTAR,
  303. Fabmaster, P-CAD, SolidWorks PCB and binary Cadence Allegro `.brd` files via
  304. KiCad 10's native importer.
  305. - **Hierarchical schematics**: `remove_hierarchical_sheet`,
  306. `set_sheet_property`, `get_sheet_properties`, and `hierarchical_place` for
  307. arranging footprints by schematic hierarchy.
  308. - **Schematic lint and repair**: `lint_offgrid` finds and safely snaps
  309. off-grid geometry that silently breaks junction placement;
  310. `repair_flat_symbols` fixes SnapEDA/SamacSys symbols that crash kicad-skip;
  311. `lint_schematic_cosmetic` tidies pin names and label orientation.
  312. - **Board origins**: `set_board_origin` / `get_board_origin`.
  313. ### Your `.kicad_pro` net classes stop disappearing
  314. Board saves no longer let pcbnew serialize a stale in-memory project model
  315. over your hand-edited net classes and `netclass_patterns`. Opening a project
  316. no longer rewrites the file at all.
  317. ### Breaking: schematic tools fail loudly on an unparseable sheet
  318. Tools that used to return partial or empty results now return a structured
  319. `schematic_load_failed` error naming the offending symbols. Silently skipping
  320. a broken sheet produced an incomplete pad-to-net map reported as success,
  321. which is worse. `repair_flat_symbols` fixes the usual cause. See
  322. [KNOWN_ISSUES.md](docs/KNOWN_ISSUES.md) section 7.
  323. Full details in the [CHANGELOG](CHANGELOG.md).
  324. ## What's New in v2.5.0
  325. ### 20 new board-lifecycle and geometry tools
  326. - **Lifecycle**: `open_board`, `reload_board`, `save_board`, `save_as`,
  327. `is_dirty`, `discard_or_reload`, `create_board_from_schematic`.
  328. - **Graphics editing**: `clear_board_outline`, `replace_board_outline`,
  329. `list_graphics`, `delete_graphic`, `update_graphic`, `move_footprint_text`.
  330. - **Geometry queries**: `batch_move_components`, `get_component_geometry`,
  331. `get_pads`, `get_net_pads`, `get_ratsnest`, `estimate_airwire_lengths`,
  332. `check_placement_clearance`.
  333. All of them respect backend session pinning, so a board saved while KiCad's
  334. GUI owns the session routes to the GUI rather than writing a stale in-memory
  335. copy — including the awkward case where `save_as` changes the board's
  336. identity mid-session.
  337. ### Formatting is normalized and enforced
  338. - `pre-commit run --all-files` (black, isort, prettier, flake8, mypy, eslint)
  339. is now a real CI gate, which is what CONTRIBUTING has always claimed.
  340. - `npm run lint` used to run `black` in **write** mode against whatever
  341. `black` was on `PATH`, silently reformatting your working tree with a
  342. version that disagreed with CI. It now checks only; `npm run format:py` is
  343. the write path.
  344. - The README's tool count is pinned to the registry by a test, so it
  345. self-corrects instead of drifting.
  346. Full details in the [CHANGELOG](CHANGELOG.md).
  347. ## What's New in v2.4.1
  348. ### Three tools that were registered but had no backend now work
  349. - `assign_net_to_class`, `check_clearance` and `set_layer_constraints` each had
  350. a full schema and a router entry but no dispatch handler, so every call
  351. returned `Unknown command`. Found by a documentation-coverage audit.
  352. - Per-layer constraints are written to a project-scoped `.kicad_dru`
  353. custom-rules file, which `kicad-cli pcb drc` and the GUI both pick up — there
  354. is no pcbnew API for them.
  355. ### Silent failures removed
  356. - `autoroute` was abandoned by the Node bridge at 30 s while Freerouting was
  357. still running, reporting failure against a valid `.ses` that existed on disk.
  358. Its timeout now derives from the `timeout` and `attempts` you pass.
  359. - `get_board_2d_view` omitted `--layers` entirely when no layers were given,
  360. and KiCad 9+ then refuses the export — producing no file at all.
  361. - `create_zone` raised `AttributeError` on every call over the IPC backend.
  362. ### New part-sourcing tools
  363. - `search_parts_registry` / `get_registry_part` / `download_registry_part`
  364. reuse a verified existing footprint or symbol instead of generating one.
  365. Downloads are host-allowlisted, extension-checked and size-capped.
  366. - `get_jlcpcb_part` returns live stock and tiered pricing when JLCPCB Open
  367. Platform credentials are configured, falling back to the local snapshot.
  368. ### CI now actually runs the test suite
  369. - The Python job had been a no-op in four independent ways, and Actions was
  370. disabled repo-wide — 32 failed runs and 0 successes across the project's
  371. whole history. All 1551 Python and 63 TypeScript tests now gate every push.
  372. Full details in the [CHANGELOG](CHANGELOG.md).
  373. ## What's New in v2.4.0
  374. ### Symbol library management
  375. - `import_symbol` / `export_symbol` / `rename_symbol` copy a symbol between
  376. `.kicad_sym` libraries, extract one to a standalone file, and rename a
  377. symbol including its sub-symbol shards and any `(extends ...)` references
  378. from derived symbols in the same library.
  379. - `add_symbol_property` and `add_library_symbol_property` set custom BOM
  380. fields (Manufacturer, MPN, LCSC, ...) on a library symbol or on a
  381. schematic's cached definition.
  382. - `update_symbol_from_library` refreshes cached `lib_symbols` definitions
  383. across one schematic, a list, or every project under a directory —
  384. the programmatic equivalent of KiCad's Update Symbol from Library.
  385. - `replace_instance_lib_ids` swaps `lib_id` references per an explicit
  386. old-to-new mapping, for migrating a schematic between libraries.
  387. ### Faster symbol discovery
  388. - Library directories, resolved paths, extracted symbol blocks, and parsed
  389. symbol lists are now cached process-wide instead of being rebuilt for every
  390. component add. Staleness guards revalidate paths and track source `mtime_ns`,
  391. and the mutating write paths clear the caches explicitly.
  392. ### Fixes that restore basic operation
  393. - Every `.kicad_sym` and schematic write raised `TypeError` on Python 3.9, the
  394. project's declared floor — `Path.write_text` did not accept `newline` until
  395. 3.10.
  396. - JLCPCB part search could not find hyphenated MPNs.
  397. - Eagle import wrote a KiCad 9 schematic header; it now writes the KiCad 10
  398. header, verified against real `kicad-cli` 10.0.
  399. - Component placement snaps to the 1.27 mm grid, `import_ses` no longer
  400. creates phantom slashless nets, and `export_dsn`/`autoroute` keep
  401. `.kicad_pro` net classes.
  402. Full details in the [CHANGELOG](CHANGELOG.md).
  403. ## What's New in v2.3.1
  404. ### Eagle schematic import
  405. - `import_eagle_schematic` converts Eagle `.sch` XML designs to KiCad format
  406. with symbol mapping, net wires, multi-gate parts, dangling-wire pruning,
  407. and ground-truth ERC reporting via `kicad-cli`.
  408. ### 3D model tools and interactive reload
  409. - `add_component_3d_model` / `remove_component_3d_model` for attaching
  410. STEP/WRL models to footprints.
  411. - Opt-in `KICAD_INTERACTIVE_SCHEMATIC=1` auto-confirms KiCad's reload dialog
  412. on Windows after schematic writes.
  413. ### Scaffolding cluster complete
  414. - New projects start blank (no `_TEMPLATE_*` symbols leaked into user files).
  415. - `.kicad_pro` files match what KiCad itself writes.
  416. - Format version `20260101` ensures all KiCad 10.0.x builds can open
  417. generated schematics.
  418. ### KiCad 10 compatibility
  419. - Derived symbols in `.kicad_symdir` libraries resolve their parent from
  420. sibling shards.
  421. - Unified install discovery finds relocated Windows installs via registry.
  422. - User env-var placeholders from `kicad_common.json` are resolved in library
  423. paths.
  424. - Phantom cross-unit pin reports in `get_wire_connections` are eliminated.
  425. Full details in the [CHANGELOG](CHANGELOG.md).
  426. ## What's New in v2.3.0
  427. ### Schematic corruption on KiCad 10 — both mechanisms fixed
  428. - **Complete instance blocks**: placed components now carry the real project
  429. name, root-sheet uuid path, per-pin uuid entries (ERC can bind wires to
  430. pins), and the full KiCad 10 field set — verified byte-equivalent to what
  431. eeschema itself writes. Previously, dragging or editing a placed symbol
  432. could crash KiCad.
  433. - **Canonical multi-line writes**: schematic tools no longer minify the whole
  434. file onto one line. Tool writes now match eeschema's "Save" byte-for-byte,
  435. with a self-check on every write that can never corrupt data. Already-
  436. minified files are repairable with `scripts/kicad_sch_reformat.py`.
  437. ### Your edits are protected
  438. - **Backend session pinning**: a loaded project stays on one backend
  439. (SWIG or IPC) for its whole lifecycle — saves can no longer silently route
  440. to a stale GUI board and lose your edits.
  441. - **External-edit guard**: `save_project` refuses to overwrite a board file
  442. whose contents changed on disk since load (pass `force: true` to override).
  443. - **`close_project`** (new tool): release the project so files can be edited
  444. directly, then reopen — no more restart choreography.
  445. ### Works on a stock Windows install
  446. - `kicad-cli` and 7-Zip are resolved from their install locations even when
  447. not on PATH — un-breaking exports, ERC/DRC, netlists, board views, and the
  448. JLCPCB database download, each with actionable errors when truly missing.
  449. ### New layout tools
  450. - `suggest_placement`: connectivity-driven PCB placement optimizer (dry-run
  451. by default, deterministic).
  452. - `suggest_schematic_declutter`: re-orients overlapping net labels without
  453. touching connectivity.
  454. Plus KiCad 10 compatibility fixes (sheet renames, sharded `.kicad_symdir`
  455. libraries, IPC `Box2` board size), correct pin geometry for rotated+mirrored
  456. and multi-unit symbols, bounded IPC connects with SWIG fallback, and a real
  457. Vitest suite for the TypeScript layer. Full details in the
  458. [CHANGELOG](CHANGELOG.md).
  459. ## What's New in v2.2.3
  460. ### New Tools: FFC/Ribbon Cable Passthrough Workflow
  461. A complete workflow for designing passthrough adapter boards (e.g. Raspberry Pi CSI
  462. cable adapters) is now supported:
  463. 1. `connect_passthrough` — wires all pins of one connector to the matching pins of
  464. another in the schematic (J1 pin N → J2 pin N, auto-named nets).
  465. 2. `sync_schematic_to_board` — imports the net assignments into the PCB.
  466. 3. `route_pad_to_pad` — routes each connection with automatic via insertion when
  467. pads are on opposite copper layers.
  468. 4. `snapshot_project` — saves a named checkpoint into `<project>/snapshots/`.
  469. ### Bug Fixes (KiCAD 9 / Windows)
  470. - **Via insertion for B.Cu footprints** — `route_pad_to_pad` now correctly detects
  471. when a footprint is on B.Cu and inserts the required via. (KiCAD 9 SWIG returned
  472. `F.Cu` for all SMD pads regardless of layer — fixed.)
  473. - **Board outline rounded corners** — `add_board_outline` now correctly applies
  474. `cornerRadius` when `shape="rounded_rectangle"`.
  475. - **B.Cu placement hang** — placing a footprint on B.Cu no longer causes a ~30s
  476. freeze in KiCAD 9.
  477. ### Developer Mode
  478. Set `KICAD_MCP_DEV=1` in your Claude Desktop MCP environment to automatically save
  479. the MCP session log into the project's `logs/` folder on every `export_gerber` and
  480. `snapshot_project` call. Useful for debugging and for attaching to GitHub issues.
  481. ```json
  482. "env": {
  483. "KICAD_MCP_DEV": "1"
  484. }
  485. ```
  486. > **Privacy warning:** The session log contains your full tool call history
  487. > (including file paths and design details). **Review or delete `logs/` before
  488. > sharing a project directory publicly.**
  489. See [CHANGELOG](CHANGELOG.md) for the full list of changes in this release.
  490. ---
  491. ## What's New in v2.1.0
  492. ### Critical Schematic Workflow Fix + Complete Wiring System (Issue #26)
  493. The schematic workflow was completely broken in previous versions - **this is now fixed AND dramatically enhanced!**
  494. **What was broken:**
  495. - `create_project` only created PCB files, no schematics
  496. - `add_schematic_component` called non-existent API methods
  497. - Schematics couldn't be created or edited at all
  498. - Only 13 component types available (severe limitation)
  499. - No working wire/connection functionality
  500. **Complete Implementation (3 Phases):**
  501. **Phase 1: Component Placement Foundation**
  502. - `create_project` now creates both .kicad_pcb and .kicad_sch files
  503. - Added pre-configured template schematics with 13 common component types
  504. - Rewrote component placement to use proper `clone()` API
  505. **Phase 2: Dynamic Symbol Loading (BREAKTHROUGH!)**
  506. - **Access to ALL ~10,000 KiCad symbols** from standard libraries
  507. - Automatic detection and dynamic loading from `.kicad_sym` library files
  508. - Zero configuration required - just specify library and symbol name
  509. - Seamless integration with existing MCP tools
  510. - Full S-expression parsing and injection system
  511. **Phase 3: Intelligent Wiring System (NEW in v2.1.0)**
  512. - **Automatic pin location discovery** with rotation support (0°, 90°, 180°, 270°)
  513. - **Smart wire routing** (direct, orthogonal horizontal-first, orthogonal vertical-first)
  514. - **Power symbol support** (VCC, GND, +3V3, +5V, etc.)
  515. - **Wire graph analysis** - geometric tracing for net connectivity
  516. - **Net label management** (local, global, hierarchical labels)
  517. - **Netlist generation** with accurate component/pin connections
  518. **Technical Architecture:**
  519. The kicad-skip library cannot create symbols or wires from scratch. We implemented a comprehensive solution:
  520. 1. **Static Templates:** 13 pre-configured symbols (R, C, L, LED, etc.) for instant use
  521. 2. **Dynamic Loading:** On-demand injection of ANY symbol from KiCad libraries:
  522. - Parse `.kicad_sym` library files using S-expression parser
  523. - Inject symbol definition into schematic's `lib_symbols` section
  524. - Create offscreen template instance
  525. - Reload schematic so kicad-skip sees new template
  526. - Clone template to create actual component
  527. 3. **Wire Creation:** S-expression-based wire injection (bypasses kicad-skip API limitations)
  528. 4. **Pin Discovery:** Parse symbol definitions, apply rotation transformations, calculate absolute positions
  529. 5. **Connectivity Analysis:** Geometric wire tracing to build net connection graphs
  530. **Example - Complete Circuit Creation:**
  531. ```python
  532. # Load power symbols dynamically
  533. loader.load_symbol_dynamically(sch_path, "power", "VCC")
  534. # Place components with auto-rotation
  535. ComponentManager.add_component(sch, {
  536. "type": "STM32F103C8Tx",
  537. "library": "MCU_ST_STM32F1",
  538. "reference": "U1",
  539. "x": 100, "y": 100, "rotation": 0
  540. })
  541. # Connect with intelligent routing
  542. ConnectionManager.add_connection(sch_path, "U1", "1", "R1", "2", routing="orthogonal_h")
  543. # Connect to power nets
  544. ConnectionManager.connect_to_net(sch_path, "U1", "VDD", "VCC")
  545. # Analyze connectivity
  546. connections = ConnectionManager.get_net_connections(sch, "VCC", sch_path)
  547. # Returns: [{"component": "U1", "pin": "VDD"}, {"component": "R1", "pin": "1"}]
  548. ```
  549. **Test Results:**
  550. - Component placement: 100% passing
  551. - Dynamic symbol loading: 10,000+ symbols accessible
  552. - Wire creation: 100% passing (8/8 connections in test circuit)
  553. - Pin discovery: Rotation-aware, sub-millimeter accuracy
  554. - Net connectivity: 100% accurate (VCC: 2 connections, GND: 4 connections)
  555. - Netlist generation: Working with accurate pin-level connections
  556. See [Schematic Tools Reference](docs/SCHEMATIC_TOOLS_REFERENCE.md) for the complete schematic tool documentation, and the [Headless Authoring Guide](docs/HEADLESS_AUTHORING.md) for field-tested practice driving these tools without the KiCad GUI.
  557. ### IPC Backend (Experimental)
  558. We are currently implementing and testing the KiCAD 9.0 IPC API for real-time UI synchronization:
  559. - Changes made via MCP tools appear immediately in the KiCAD UI
  560. - No manual reload required when IPC is active
  561. - Hybrid backend: uses IPC when available, falls back to SWIG API
  562. - IPC runtime reconnect: if MCP has fallen back to SWIG, IPC-capable board
  563. tools retry IPC after KiCAD launches instead of staying on SWIG for the entire
  564. session
  565. - 20+ commands now support IPC including routing, component placement, and zone operations
  566. Note: IPC features are under active development and testing. Enable IPC in KiCAD via Preferences > Plugins > Enable IPC API Server.
  567. For OpenCode on Windows, the backend can be configured as `auto`, `ipc`, or
  568. `swig` during setup. See [OpenCode (Windows)](#opencode-windows) for the
  569. configuration command and backend options.
  570. ### Tool Discovery
  571. Every tool is registered individually, so an MCP client can call any of them by
  572. name. Every tool is also indexed, so an assistant can find one by keyword
  573. instead of guessing:
  574. - **33 core tools** that `search_tools` surfaces first, covering the
  575. operations nearly every session needs
  576. - **20 categories** (board, component, export, drc, schematic, library,
  577. symbol_library, symbol_pins, schematic_hierarchy, schematic_layout,
  578. schematic_batch, routing, autoroute, validation, parts-registry, digikey,
  579. gui-driver, footprint, import, jlcpcb)
  580. - **Discovery tools**:
  581. - `list_tool_categories` - Browse all available categories
  582. - `get_category_tools` - View tools in a specific category
  583. - `search_tools` - Find tools by keyword
  584. **Why this matters:** the assistant can locate the right tool for your task by
  585. keyword rather than inventing a name. Discovery on its own does _not_ reduce
  586. context: by default every tool schema is still sent to the client. Toolboxes,
  587. below, do.
  588. ### Toolboxes
  589. The full set is about 250 tool definitions. Every one a client loads costs
  590. context, and some clients cap the count: VS Code Copilot stops at 128 tools.
  591. Set `KICAD_MCP_TOOLBOXES` in the server's environment to load only what you
  592. need. Each category above is a toolbox.
  593. | Setting | What the client sees |
  594. | --------------------------------------- | ------------------------------------------------------------------------------ |
  595. | not set, or `all` | Every tool, as before |
  596. | `core` | The 33 core tools, `search_tools`, and the toolbox controls (37 tools) |
  597. | a list, such as `schematic,drc,routing` | The same, plus those toolboxes from the start (names match case-insensitively) |
  598. With toolboxes on, the assistant gets three controls in place of
  599. `list_tool_categories` and `get_category_tools`:
  600. - `list_toolboxes` - every toolbox with its description, its tools, and whether it is open
  601. - `open_toolbox` - add one or more toolboxes' tools to the tool list
  602. - `close_toolbox` - remove them again to free context
  603. Opened tools are ordinary tools with their real schemas: the server tells the
  604. client its tool list changed, and the client reads it again. How quickly they
  605. can be used depends on the client:
  606. - **Claude Code, VS Code Copilot:** from your next message. The assistant
  607. opens a toolbox and says so; your reply lets it continue.
  608. - **Claude Desktop:** only after a restart, because it does not re-read the
  609. list. Name the toolboxes you need in `KICAD_MCP_TOOLBOXES` instead.
  610. An earlier design saved context by hiding tools behind an `execute_tool`
  611. dispatcher. It was removed because the model then invented arguments for tools
  612. whose schemas it had never been shown; toolboxes avoid that by never calling a
  613. tool indirectly. See [ROUTER_ARCHITECTURE.md](docs/ROUTER_ARCHITECTURE.md) for
  614. that history.
  615. ### Operating modes
  616. `KICAD_MCP_OPERATING_MODE` limits what the assistant can do, for example to let
  617. a review agent inspect a design without any way to change it:
  618. | Setting | What the client gets |
  619. | ------------------- | ----------------------------------------------------------------------------------------------------- |
  620. | not set, or `write` | Every tool, as before |
  621. | `readonly` | Only tools that cannot change the design, project, libraries or KiCad settings, nor drive KiCad's GUI |
  622. | `manufacturing` | `readonly` plus the export tools (Gerber, drill, PDF, BOM, netlist, 3D and so on) |
  623. - Tools the mode doesn't allow are removed from the tool list, and the server
  624. rejects calls to them.
  625. - Read-only tools may still write output files outside the design, such as a
  626. DRC report or a rendered preview.
  627. - The mode combines with [toolboxes](#toolboxes): a tool is offered only when
  628. both allow it.
  629. - A value the server doesn't recognise counts as `readonly`, so a typo never
  630. grants write access.
  631. - Every read-only tool also carries MCP's `readOnlyHint` annotation, which some
  632. clients use to skip approval prompts.
  633. **Usage is seamless:** Just ask naturally - "export gerber files" or "add mounting holes" - and Claude will find and call the appropriate tools automatically.
  634. ### NEEDS TESTING - REPORT ISSUES
  635. ### JLCPCB Parts Integration (New!)
  636. Complete integration with JLCPCB's parts catalog, providing two complementary approaches for component selection:
  637. **Dual-Mode Architecture:**
  638. 1. **Local Symbol Libraries** - Search JLCPCB libraries installed via KiCAD Plugin and Content Manager (contributed by [@l3wi](https://github.com/l3wi))
  639. 2. **JLCPCB API Integration** - Access the complete 2.5M+ parts catalog with real-time pricing and stock data
  640. **Key Features:**
  641. - Real-time pricing with quantity breaks (1+, 10+, 100+, 1000+)
  642. - Stock availability checking
  643. - Basic vs Extended library type identification (Basic = free assembly)
  644. - Intelligent cost optimization with alternative part suggestions
  645. - Package-to-footprint mapping for KiCAD compatibility
  646. - Parametric search by category, package, manufacturer
  647. - Local SQLite database for fast offline searching
  648. - No API credentials required for local library search
  649. **Why this matters:** JLCPCB offers PCB assembly services where Basic parts have no assembly fee, while Extended parts charge $3 per unique component. This integration helps you find the cheapest components with the best availability, potentially saving hundreds of dollars on assembly costs for production runs.
  650. See [JLCPCB Usage Guide](docs/JLCPCB_USAGE_GUIDE.md) for detailed setup and usage instructions.
  651. ### Comprehensive Tool Schemas
  652. Every tool now includes complete JSON Schema definitions with:
  653. - Detailed parameter descriptions and constraints
  654. - Input validation with type checking
  655. - Required vs. optional parameter specifications
  656. - Enumerated values for categorical inputs
  657. - Clear documentation of what each tool does
  658. ### Resources Capability
  659. Access project state without executing tools:
  660. - `kicad://project/current/info` - Project metadata
  661. - `kicad://project/current/board` - Board properties
  662. - `kicad://project/current/components` - Component list (JSON)
  663. - `kicad://project/current/nets` - Electrical nets
  664. - `kicad://project/current/layers` - Layer stack configuration
  665. - `kicad://project/current/design-rules` - Current DRC settings
  666. - `kicad://project/current/drc-report` - Design rule violations
  667. - `kicad://board/preview.png` - Board visualization (PNG)
  668. ### Protocol Compliance
  669. - Updated to MCP SDK 1.21.0 (latest)
  670. - Full JSON-RPC 2.0 support
  671. - Proper capability negotiation
  672. - Standards-compliant error codes
  673. ## Available Tools
  674. The server exposes every tool directly, so your assistant can call any of them without a discovery step -- just ask for what you want to accomplish. All **257 tools** are also indexed into 20 functional categories, so `search_tools` and `get_category_tools` can find one by keyword, and each category doubles as a [toolbox](#toolboxes).
  675. The lists below are a curated tour of the most useful tools, not the full set.
  676. For the complete, generated reference of all 257 tools -- including how each one
  677. is discovered -- see [Tool Inventory](docs/TOOL_INVENTORY.md).
  678. ### Project Management (12 tools)
  679. - `create_project` - Initialize new KiCAD projects
  680. - `open_project` - Load existing project files
  681. - `open_board` / `reload_board` - Open or re-read a specific `.kicad_pcb`
  682. - `save_project` / `save_board` / `save_as` - Save current state
  683. - `close_project` - Save (optionally) and drop in-memory state
  684. - `is_dirty` / `discard_or_reload` - Check for and undo unsaved changes
  685. - `get_project_info` - Retrieve project metadata
  686. - `snapshot_project` - Save named checkpoint snapshot
  687. ### Board Operations (19 tools)
  688. - `set_board_size` - Configure PCB dimensions
  689. - `add_board_outline` - Create board edge (rectangle, circle, polygon, rounded rectangle)
  690. - `add_layer` - Add custom layers to stack
  691. - `set_active_layer` - Switch working layer
  692. - `get_layer_list` - List all board layers
  693. - `get_board_info` - Retrieve board properties
  694. - `get_board_2d_view` - Generate board preview image
  695. - `get_board_extents` - Get board bounding box
  696. - `add_mounting_hole` - Place mounting holes
  697. - `add_board_text` - Add text annotations
  698. - `add_zone` - Add copper zone/pour with clearance settings
  699. - `clear_board_outline` / `replace_board_outline` - Remove or swap the Edge.Cuts outline
  700. - `set_board_origin` / `get_board_origin` - Read and set the drill/place and grid origins
  701. - `list_graphics` / `update_graphic` / `delete_graphic` - Inspect and edit drawing items
  702. - `import_svg_logo` - Import SVG file as PCB silkscreen polygons
  703. ### Component Management (28 tools)
  704. - `place_component` - Place single component with footprint
  705. - `move_component` - Reposition existing component
  706. - `rotate_component` - Rotate component by angle
  707. - `delete_component` - Remove component from board
  708. - `edit_component` - Modify component properties
  709. - `find_component` - Search by reference or value
  710. - `get_component_properties` - Query component details
  711. - `add_component_annotation` - Add annotation/comment
  712. - `group_components` - Group multiple components
  713. - `replace_component` - Replace with different footprint
  714. - `get_component_pads` - Get all pad information
  715. - `get_component_list` - List all placed components
  716. - `get_pad_position` - Get precise pad position
  717. - `place_component_array` - Create component grids/patterns
  718. - `align_components` - Align multiple components
  719. - `duplicate_component` - Copy existing component
  720. - `batch_move_components` - Move many components in one transactional call
  721. - `get_component_geometry` / `check_placement_clearance` - Body sizes and overlap checks
  722. - `get_ratsnest` / `estimate_airwire_lengths` - Unrouted connection analysis
  723. ### Routing (17 tools)
  724. - `add_net` - Create electrical net
  725. - `route_trace` - Route copper traces between XY points
  726. - `route_pad_to_pad` - Route between pads with auto-via insertion
  727. - `add_via` - Place vias for layer transitions
  728. - `delete_trace` - Remove traces (by UUID, position, or net)
  729. - `query_traces` - Query/filter traces
  730. - `get_nets_list` - List all nets with statistics
  731. - `modify_trace` - Change trace width, layer, or net
  732. - `create_netclass` - Define net class with rules
  733. - `add_copper_pour` - Create copper zones/pours
  734. - `route_differential_pair` - Route differential signals
  735. - `refill_zones` - Refill all copper zones
  736. - `copy_routing_pattern` - Replicate routing between component groups
  737. - `set_net_color` - Set or clear a net's display color override
  738. - `route_arc_trace` - Route a curved trace
  739. - `add_gnd_stitching_vias` - Stitch a ground plane with vias
  740. - `query_zones` - Inspect copper zones
  741. ### Schematic (46 tools)
  742. Complete schematic workflow with dynamic symbol loading (~10,000 symbols) and intelligent wiring.
  743. **Component Operations:**
  744. - `add_schematic_component` - Place symbols from any KiCad library
  745. - `delete_schematic_component` - Remove component
  746. - `edit_schematic_component` - Edit footprint, value, reference, label positions, and **arbitrary custom properties** (MPN, Manufacturer, DigiKey_PN, LCSC, Voltage, Tolerance, Dielectric, …) in one batched call
  747. - `set_schematic_component_property` - Add or update a single custom property (BOM/sourcing field) on a component
  748. - `remove_schematic_component_property` - Delete a single custom property from a component
  749. - `get_schematic_component` - Inspect every field on a component (built-in + custom) including label positions
  750. - `list_schematic_components` - List all components
  751. - `move_schematic_component` - Reposition component
  752. - `rotate_schematic_component` - Rotate component
  753. - `annotate_schematic` - Auto-assign reference designators
  754. **Wiring and Connections:**
  755. - `add_schematic_wire` - Create wire between points
  756. - `delete_schematic_wire` - Remove wire segment
  757. - `add_no_connect` - Mark a pin as deliberately unconnected
  758. - `add_schematic_net_label` - Add net labels (VCC, GND, signals)
  759. - `delete_schematic_net_label` - Remove net label
  760. - `connect_to_net` - Connect pin to named net
  761. - `connect_passthrough` - Wire all matching pins between connectors (FFC/ribbon)
  762. - `get_schematic_pin_locations` - Get pin locations for component
  763. **Analysis and Export:**
  764. - `get_net_connections` - Trace net connectivity
  765. - `list_schematic_nets` / `list_schematic_wires` / `list_schematic_labels`
  766. - `create_schematic` - Create new schematic file
  767. - `get_schematic_view` - Rasterized schematic preview
  768. - `export_schematic_svg` / `export_schematic_pdf`
  769. - `run_erc` - Electrical rule check
  770. - `generate_netlist` - Generate netlist from schematic
  771. - `sync_schematic_to_board` - Import nets/pads to PCB (F8 equivalent)
  772. - `backannotate_footprints` - Copy footprint choices from the board back to the schematic
  773. - `create_board_from_schematic` - Create a board populated from the schematic
  774. **Batch, Hierarchy and Layout (19 more tools):**
  775. - `batch_add_components` / `batch_edit_schematic_components` / `batch_connect` - Bulk authoring
  776. - `add_hierarchical_sheet` / `create_hierarchical_subsheet` - Multi-sheet designs
  777. - `autoplace_schematic_fields` / `lint_schematic_cosmetic` - Tidy field placement
  778. - `lint_offgrid` / `snap_to_grid` - Find and fix off-grid coordinates
  779. See [Schematic Tools Reference](docs/SCHEMATIC_TOOLS_REFERENCE.md) for details and examples.
  780. ### File Validation (2 tools)
  781. Find structural damage before KiCad refuses to open a file. Both report the line
  782. and column of every fault, and confirm the verdict with `kicad-cli` run against a
  783. throwaway copy.
  784. - `validate_schematic` - Check a `.kicad_sch` file
  785. - `validate_symbol_library` - Check a `.kicad_sym` file
  786. ### Design Rules / DRC (7 tools)
  787. - `set_design_rules` / `get_design_rules` - Configure and inspect rules
  788. - `run_drc` - Execute design rule check
  789. - `get_drc_violations` - Get violation list by severity
  790. - `create_netclass` / `assign_net_to_class` - Net class management
  791. - `set_layer_constraints` / `check_clearance` - Layer and clearance rules
  792. ### Export (27 tools)
  793. - `export_gerber` / `export_gerbers` / `export_gerber_single` - Gerber fabrication files
  794. - `export_drill` - Drill files
  795. - `export_ipc2581` / `export_odb` / `export_ipcd356` / `export_gencad` - Other fabrication formats
  796. - `export_pdf` / `export_svg` / `export_pcb_dxf` - Documentation and vector graphics
  797. - `export_3d` - 3D models (STEP, STL, VRML, OBJ)
  798. - `export_bom` / `export_sch_bom` - Bill of materials (CSV, XML, HTML, JSON)
  799. - `export_netlist` - Netlist (KiCad, Spice, Cadstar, OrcadPCB2)
  800. - `export_position_file` / `export_pos` - Component positions for pick and place
  801. - `export_sch_pdf` / `export_sch_svg` / `export_sch_dxf` - Schematic output
  802. - `export_vrml` - VRML 3D model
  803. ### Footprint Libraries and Symbol Libraries (16 tools)
  804. - `list_libraries` / `list_symbol_libraries` - Browse available libraries
  805. - `search_footprints` / `search_symbols` - Search across all libraries
  806. - `list_library_footprints` / `list_library_symbols` - Browse specific library
  807. - `get_footprint_info` / `get_symbol_info` - Detailed information
  808. - `list_symbol_pins` / `batch_list_symbol_pins` - Read pins straight from a library
  809. - `set_symbol_pin_type` - Bulk-set pin electrical types, with a dry run first
  810. - `find_duplicate_symbols` - Find the same part stored twice under different names
  811. - `repair_flat_symbols` - Fix vendor symbols that KiCad tolerates but tools cannot parse
  812. **Library tables** (`sym-lib-table` / `fp-lib-table`):
  813. - `list_library_table` - Read every registered library and check its URI resolves
  814. - `remove_library_table_entry` - Unregister a library
  815. - `set_library_table_uri` - Repoint a library that moved
  816. ### Footprint Creator (7 tools) and Symbol Creator (8 tools)
  817. Create custom components when existing libraries do not have what you need.
  818. - `create_footprint` / `create_symbol` - Build from scratch with pads/pins
  819. - `edit_footprint_pad` - Modify pad properties
  820. - `add_footprint_3d_model` / `add_component_3d_model` / `import_3d_model` - Attach 3D models
  821. - `register_footprint_library` / `register_symbol_library` - Register in lib-table
  822. - `list_footprint_libraries` / `list_symbols_in_library` - Browse custom libraries
  823. - `add_symbol_property` - Add or update a field on a library symbol
  824. - `import_symbol` / `export_symbol` / `rename_symbol` - Move symbols between libraries
  825. - `delete_symbol` - Remove symbol from library
  826. See [Footprint and Symbol Creator Guide](docs/FOOTPRINT_SYMBOL_CREATOR_GUIDE.md) for details.
  827. ### Datasheet Tools (2 tools)
  828. - `enrich_datasheets` - Auto-populate datasheet URLs using LCSC part numbers
  829. - `get_datasheet_url` - Get LCSC datasheet URL for a component
  830. ### JLCPCB Integration (5 tools)
  831. - `download_jlcpcb_database` - Download 2.5M+ parts catalog (one-time setup)
  832. - `search_jlcpcb_parts` - Search with parametric filters
  833. - `get_jlcpcb_part` - Detailed part info with pricing
  834. - `get_jlcpcb_database_stats` - Database statistics
  835. - `suggest_jlcpcb_alternatives` - Find cheaper or in-stock alternatives
  836. ### Freerouting Autorouter (4 tools)
  837. - `autoroute` - Run Freerouting autorouter (DSN export, route, SES import)
  838. - `export_dsn` / `import_ses` - Manual Specctra DSN/SES workflow
  839. - `check_freerouting` - Verify Java and Freerouting availability
  840. See [Freerouting Guide](docs/FREEROUTING_GUIDE.md) for setup and usage.
  841. ### UI Management (3 tools)
  842. - `check_kicad_ui` - Check if KiCAD is running
  843. - `launch_kicad_ui` - Launch KiCAD application
  844. - `get_backend_state` - Report which backend (IPC or SWIG) is in use
  845. ### Parts Registry (3 tools)
  846. Look for a ready-made part before generating a custom one.
  847. - `search_parts_registry` - Search the registry by name, keyword or manufacturer
  848. - `get_registry_part` - Inspect one part in detail
  849. - `download_registry_part` - Download its footprint, symbol or 3D model
  850. ### Import (2 tools)
  851. - `import_eagle_project` - Convert an Eagle project
  852. - `import_pcb` - Load an existing `.kicad_pcb` into the session
  853. ## Prerequisites
  854. ### Required Software
  855. **KiCAD 9.0 or higher**
  856. - Download from [kicad.org/download](https://www.kicad.org/download/)
  857. - Must include Python module (pcbnew)
  858. - Verify installation:
  859. ```bash
  860. python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"
  861. ```
  862. **Node.js 18 or Higher**
  863. - Download from [nodejs.org](https://nodejs.org/)
  864. - Verify: `node --version` and `npm --version`
  865. **Python 3.9 or Higher**
  866. - Comes bundled with KiCAD (macOS builds ship Python 3.9; Linux/Windows builds ship Python 3.11)
  867. - Required packages (auto-installed):
  868. - kicad-python (kipy) >= 0.5.0 (IPC API support, optional but recommended)
  869. - kicad-skip >= 0.1.0 (schematic support)
  870. - Pillow >= 9.0.0 (image processing)
  871. - cairosvg >= 2.7.0 (SVG rendering)
  872. - colorlog >= 6.7.0 (logging)
  873. - pydantic >= 2.5.0 (validation)
  874. - requests >= 2.32.5 (HTTP client)
  875. - python-dotenv >= 1.0.0 (environment)
  876. **MCP Client**
  877. Choose one:
  878. - [Claude Desktop](https://claude.ai/download) - Official Anthropic desktop app
  879. - [Claude Code](https://docs.claude.com/claude-code) - Official CLI tool
  880. - [Cline](https://github.com/cline/cline) - VSCode extension
  881. - [OpenCode](https://opencode.ai/) - Terminal-based AI coding agent with MCP support
  882. ### Supported Platforms
  883. - **Linux** (Ubuntu 22.04+, Fedora, Arch) - Primary platform, fully tested
  884. - **Windows 10/11** - Fully supported with automated setup
  885. - **macOS** - Experimental support
  886. ## Installation
  887. These steps install the latest release from the `stable` branch, which only
  888. moves when a version is released. `main` also has fixes that are not released
  889. yet; clone without `--branch stable` to use it. To update an install later, run
  890. `git pull` in the clone, then `npm install` and `npm run build` again.
  891. ### Linux (Ubuntu/Debian)
  892. ```bash
  893. # Install KiCAD 9.0 or higher
  894. sudo add-apt-repository --yes ppa:kicad/kicad-9.0-releases
  895. sudo apt-get update
  896. sudo apt-get install -y kicad kicad-libraries
  897. # Install Node.js
  898. curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
  899. sudo apt-get install -y nodejs
  900. # Clone and build
  901. git clone --branch stable https://github.com/mixelpixx/KiCAD-MCP-Server.git
  902. cd KiCAD-MCP-Server
  903. npm install
  904. pip3 install -r requirements.txt
  905. npm run build
  906. # Verify
  907. python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"
  908. ```
  909. #### Automated Claude Desktop configuration
  910. [`scripts/install-linux.sh`](scripts/install-linux.sh) installs KiCad, Node.js,
  911. and dependencies; [`setup-linux.sh`](setup-linux.sh) then configures the MCP client.
  912. After installing the dependencies and building the project, use the Linux setup
  913. script to detect KiCad's Python bindings and safely merge the MCP entry into
  914. Claude Desktop's configuration. It preserves virtual-environment package
  915. precedence and checks Python dependencies using the generated environment:
  916. ```bash
  917. ./setup-linux.sh --verify
  918. ./setup-linux.sh --dry-run
  919. ./setup-linux.sh --apply
  920. ```
  921. `--verify` fails if a dependency is missing or cannot be imported and prints an
  922. installation command for the selected Python interpreter. `--dry-run` previews
  923. the configuration and reports dependency problems; `--apply` requires those
  924. problems to be fixed before writing the configuration.
  925. The default configuration path is
  926. `${XDG_CONFIG_HOME:-~/.config}/Claude/claude_desktop_config.json`. Use
  927. `--claude-config PATH` for a client using the same JSON format or a nonstandard location, and set
  928. `KICAD_PYTHON=/path/to/python3` if KiCad's Python cannot be detected automatically.
  929. ### Windows 10/11
  930. **Automated Setup (Recommended):**
  931. ```powershell
  932. git clone --branch stable https://github.com/mixelpixx/KiCAD-MCP-Server.git
  933. cd KiCAD-MCP-Server
  934. .\setup-windows.ps1
  935. ```
  936. The script will:
  937. - Detect KiCAD installations, including both machine-wide installs under
  938. `C:\Program Files\KiCad` and per-user installs under
  939. `%LOCALAPPDATA%\Programs\KiCad`
  940. - Verify prerequisites
  941. - Install dependencies
  942. - Build project
  943. - Generate configuration
  944. - Run diagnostics
  945. **Manual Setup:**
  946. See [Platform Guide](docs/PLATFORM_GUIDE.md) for detailed instructions, and
  947. [Windows Troubleshooting](docs/WINDOWS_TROUBLESHOOTING.md) if setup fails.
  948. ### macOS
  949. **Important:** On macOS, use KiCAD's bundled Python to ensure proper access to the `pcbnew` module.
  950. #### Manual Setup
  951. ```bash
  952. # Install KiCAD 9.0 from kicad.org/download/macos
  953. # Install Node.js
  954. brew install node@20
  955. # Clone repository
  956. git clone --branch stable https://github.com/mixelpixx/KiCAD-MCP-Server.git
  957. cd KiCAD-MCP-Server
  958. # Create virtual environment using KiCAD's bundled Python
  959. /Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3 -m venv venv --system-site-packages
  960. # Activate virtual environment
  961. source venv/bin/activate
  962. # Install dependencies
  963. npm install
  964. pip install -r requirements.txt
  965. npm run build
  966. ```
  967. **Note:** The `--system-site-packages` flag is required to access KiCAD's `pcbnew` module from the virtual environment.
  968. **Note:** If you skip the virtual environment, install the requirements with KiCAD's bundled interpreter — a plain `pip3 install -r requirements.txt` goes to system Python, which the server never uses, and the server then fails to start (the MCP client times out after 30s with no visible error):
  969. ```bash
  970. /Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3 \
  971. -m pip install --user -r requirements.txt
  972. ```
  973. #### Automated Setup
  974. To simplify configuration with Claude Desktop, this repository provides a macOS setup script:
  975. ```bash
  976. ./setup-macos.sh
  977. ```
  978. In case of error `zsh: permission denied: ./setup-macos.sh` you can either:
  979. - always allow the script to be executed by running: `chmod +x setup-macos.sh`.
  980. - alternatively explicitly run it with bash: `bash setup-macos.sh` so no chmod change needed.
  981. This script does **not replace the manual setup above** — it assumes dependencies are already installed and the project is built. Instead, it automates:
  982. - detection of your environment (Node.js, KiCad Python, `pcbnew`)
  983. - resolving the correct macOS `PYTHONPATH`
  984. - generating the correct Claude Desktop MCP configuration
  985. - safely merging the configuration into your existing Claude config
  986. - optionally writing the configuration with backup support
  987. ##### Basic Usage
  988. ###### Verify setup (no changes)
  989. ```bash
  990. ./setup-macos.sh --verify
  991. ```
  992. ###### Preview configuration (dry run)
  993. ```bash
  994. ./setup-macos.sh --dry-run
  995. ```
  996. ###### Apply configuration
  997. ```bash
  998. ./setup-macos.sh --apply
  999. ```
  1000. After applying, restart Claude Desktop.
  1001. ##### Parameters
  1002. ###### Required parameters
  1003. None. The script works out-of-the-box using sensible defaults.
  1004. ###### Optional parameters
  1005. ##### `--name NAME`
  1006. Specify the MCP server name in Claude Desktop.
  1007. Default:
  1008. ```text
  1009. kicad
  1010. ```
  1011. Example:
  1012. ```bash
  1013. ./setup-macos.sh --apply --name kicad-dev
  1014. ```
  1015. Use this when:
  1016. - running multiple MCP configurations
  1017. - testing forks or development versions
  1018. - avoiding overwriting an existing setup
  1019. ##### `--claude-config PATH`
  1020. Specify a custom Claude Desktop configuration file.
  1021. Default:
  1022. ```text
  1023. ~/Library/Application Support/Claude/claude_desktop_config.json
  1024. ```
  1025. Example:
  1026. ```bash
  1027. ./setup-macos.sh --dry-run --claude-config ~/tmp/claude_config.json
  1028. ```
  1029. Use this when:
  1030. - testing configurations safely
  1031. - using non-standard config locations
  1032. - debugging without modifying your main setup
  1033. ##### `--yes`
  1034. Skip confirmation prompt when applying changes.
  1035. Example:
  1036. ```bash
  1037. ./setup-macos.sh --apply --yes
  1038. ```
  1039. ##### After Setup
  1040. 1. Fully quit Claude Desktop
  1041. 2. Reopen Claude Desktop
  1042. 3. Open a new chat
  1043. 4. Click **+ → Connectors**
  1044. 5. Verify the server appears (e.g. `kicad` or your custom name)
  1045. Test with prompt in Claude Desktop:
  1046. ```text
  1047. Use the kicad MCP server to run check_kicad_ui.
  1048. ```
  1049. ##### Notes
  1050. - The script only modifies the `mcpServers` section and leaves all other configuration untouched
  1051. - Existing configurations are automatically backed up before changes
  1052. - macOS support relies on KiCad’s bundled Python; system Python will not work correctly
  1053. - If KiCad is updated or moved, re-run the script to refresh paths
  1054. ---
  1055. ## Configuration
  1056. ### Claude Desktop
  1057. Edit configuration file:
  1058. - **Linux:** `~/.config/Claude/claude_desktop_config.json`
  1059. - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
  1060. - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
  1061. **Configuration:**
  1062. ```json
  1063. {
  1064. "mcpServers": {
  1065. "kicad": {
  1066. "command": "node",
  1067. "args": ["/path/to/KiCAD-MCP-Server/dist/index.js"],
  1068. "env": {
  1069. "PYTHONPATH": "/path/to/kicad/python",
  1070. "LOG_LEVEL": "info"
  1071. }
  1072. }
  1073. }
  1074. }
  1075. ```
  1076. **Platform-specific PYTHONPATH:**
  1077. - **Linux:** `/usr/lib/kicad/lib/python3/dist-packages`
  1078. - **Windows:** `C:\Program Files\KiCad\10.0\lib\python3\dist-packages` or
  1079. `%LOCALAPPDATA%\Programs\KiCad\10.0\lib\python3\dist-packages`
  1080. - **macOS:** `/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/3.9/lib/python3.9/site-packages`
  1081. #### Linux Python Detection
  1082. The server automatically detects Python on Linux in this priority order:
  1083. 1. **Virtual environment** - `venv/bin/python` or `.venv/bin/python` (highest priority)
  1084. 2. **KICAD_PYTHON env var** - User override for non-standard installations
  1085. 3. **KiCad bundled Python** - `/usr/lib/kicad/bin/python3`, `/usr/local/lib/kicad/bin/python3`, `/opt/kicad/bin/python3`
  1086. 4. **System Python via which** - Resolves `which python3` to absolute path (e.g., `/usr/bin/python3`)
  1087. 5. **Common system paths** - `/usr/bin/python3`, `/bin/python3`
  1088. **For most standard Linux installations (Ubuntu, Debian, Fedora, Arch), no KICAD_PYTHON configuration is needed** - the server will automatically find your Python installation.
  1089. **Troubleshooting:**
  1090. If you see "Python executable not found: python3", you can manually specify the Python path:
  1091. ```json
  1092. {
  1093. "mcpServers": {
  1094. "kicad": {
  1095. "command": "node",
  1096. "args": ["/path/to/KiCAD-MCP-Server/dist/index.js"],
  1097. "env": {
  1098. "KICAD_PYTHON": "/usr/bin/python3",
  1099. "PYTHONPATH": "/usr/lib/kicad/lib/python3/dist-packages"
  1100. }
  1101. }
  1102. }
  1103. }
  1104. ```
  1105. To find your Python path:
  1106. ```bash
  1107. which python3 # Example output: /usr/bin/python3
  1108. python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())" # Verify pcbnew access
  1109. ```
  1110. ### GitHub Copilot (VS Code)
  1111. Copy the template to your workspace:
  1112. ```bash
  1113. cp config/vscode-mcp.example.json .vscode/mcp.json
  1114. ```
  1115. VS Code will auto-detect `.vscode/mcp.json` and register the server. The template uses `${workspaceFolder}` so no path editing is needed.
  1116. > **Note:** `.vscode/mcp.json` is listed in `.gitignore` — your local configuration won't be committed.
  1117. ### Cline (VSCode)
  1118. Edit: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
  1119. Use the same configuration format as Claude Desktop above.
  1120. ### Claude Code
  1121. Claude Code does **not** read the Claude Desktop configuration file, and it only auto-detects servers listed in a project's `.mcp.json` (this repository does not ship one). Register the server explicitly with `claude mcp add`:
  1122. ```bash
  1123. # macOS example — adjust KICAD_PYTHON/PYTHONPATH per platform (see table above)
  1124. claude mcp add --scope user kicad \
  1125. --env KICAD_PYTHON=/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3 \
  1126. --env PYTHONPATH=/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/3.9/lib/python3.9/site-packages \
  1127. --env LOG_LEVEL=info \
  1128. -- node /path/to/KiCAD-MCP-Server/dist/index.js
  1129. ```
  1130. With `--scope user` the server is available in every project; use `--scope project` to write a shareable `.mcp.json` instead. On macOS, `setup-macos.sh` prints this command with the detected paths filled in.
  1131. Verify with `claude mcp list` — the server should report ✔ Connected.
  1132. ### OpenCode (Windows)
  1133. OpenCode uses a different MCP configuration schema than Claude Desktop. Use
  1134. `setup-windows-opencode.ps1` to verify the local setup and write the correct
  1135. OpenCode `mcp` entry.
  1136. OpenCode project configuration is written to `opencode.json` in the target
  1137. project root. The script keeps the KiCAD MCP server repository separate from the
  1138. target project:
  1139. - `McpServerPath` is this repository, where `dist/index.js` is built
  1140. - `ProjectPath` is the project that should receive `opencode.json`
  1141. **When this is useful:**
  1142. - You use [OpenCode](https://opencode.ai/) as your MCP client on Windows
  1143. - You want a project-local MCP server available only in one project
  1144. - You want a global OpenCode MCP server available from any workspace
  1145. - You need to verify KiCAD Python (`pcbnew`), Node.js, and `dist/index.js`
  1146. before changing OpenCode configuration
  1147. #### Backend selection
  1148. The setup script supports three KiCAD backend preferences via `-Backend`:
  1149. - `auto` - try IPC first and fall back to SWIG if IPC is unavailable (default)
  1150. - `ipc` - require KiCAD IPC for real-time UI synchronization
  1151. - `swig` - use the file-based `pcbnew` backend
  1152. Examples:
  1153. ```powershell
  1154. .\setup-windows-opencode.ps1 -Apply -Scope project -Backend auto
  1155. .\setup-windows-opencode.ps1 -Apply -Scope project -Backend ipc
  1156. .\setup-windows-opencode.ps1 -Apply -Scope project -Backend swig
  1157. ```
  1158. For `-Backend ipc`, KiCAD must be running with the IPC API server enabled.
  1159. #### Verify setup without changes
  1160. Use this first when diagnosing installation or path problems. It detects KiCAD,
  1161. tests `pcbnew`, checks Node.js, and verifies the built MCP entrypoint.
  1162. ```powershell
  1163. .\setup-windows-opencode.ps1 -Verify -SkipInstall -SkipBuild
  1164. ```
  1165. #### Preview OpenCode configuration
  1166. Use dry run mode when you want to inspect the exact JSON before writing it.
  1167. ```powershell
  1168. .\setup-windows-opencode.ps1 -DryRun -SkipInstall -SkipBuild
  1169. ```
  1170. Example generated OpenCode shape:
  1171. ```json
  1172. {
  1173. "$schema": "https://opencode.ai/config.json",
  1174. "mcp": {
  1175. "kicad": {
  1176. "type": "local",
  1177. "command": ["node", "C:\\path\\to\\KiCAD-MCP-Server\\dist\\index.js"],
  1178. "environment": {
  1179. "NODE_ENV": "production",
  1180. "LOG_LEVEL": "info",
  1181. "KICAD_AUTO_LAUNCH": "false",
  1182. "KICAD_MCP_DEV": "0",
  1183. "KICAD_BACKEND": "auto",
  1184. "PYTHONPATH": "C:\\Program Files\\KiCad\\10.0\\bin\\Lib\\site-packages"
  1185. },
  1186. "enabled": true,
  1187. "timeout": 30000
  1188. }
  1189. }
  1190. }
  1191. ```
  1192. A copyable template is also provided at `config/opencode.json`. Replace the
  1193. placeholder paths before using it directly.
  1194. #### Apply project-local configuration
  1195. Use this when you only want KiCAD MCP enabled for one project. The script writes
  1196. `opencode.json` in the target project root and backs up an existing file before
  1197. changing it.
  1198. ```powershell
  1199. .\setup-windows-opencode.ps1 -Apply -Scope project
  1200. ```
  1201. By default, `ProjectPath` is the current working directory.
  1202. To configure another project, pass `-ProjectPath`:
  1203. ```powershell
  1204. .\setup-windows-opencode.ps1 -Apply -Scope project -ProjectPath "C:\path\to\your-project"
  1205. ```
  1206. If the setup script is not located in the KiCAD MCP Server repository, pass
  1207. `-McpServerPath` so the generated config points to the correct `dist/index.js`:
  1208. ```powershell
  1209. .\setup-windows-opencode.ps1 `
  1210. -Apply `
  1211. -Scope project `
  1212. -ProjectPath "C:\path\to\your-project" `
  1213. -McpServerPath "C:\path\to\KiCAD-MCP-Server"
  1214. ```
  1215. #### Apply global OpenCode configuration
  1216. Use this when you want the KiCAD MCP server available from any OpenCode
  1217. workspace. The script writes `%USERPROFILE%\.config\opencode\opencode.json`.
  1218. ```powershell
  1219. .\setup-windows-opencode.ps1 -Apply -Scope global
  1220. ```
  1221. #### Use a custom MCP server name
  1222. Use this when testing multiple forks or keeping separate development and stable
  1223. KiCAD MCP entries.
  1224. ```powershell
  1225. .\setup-windows-opencode.ps1 -Apply -Scope project -Name kicad-dev
  1226. ```
  1227. #### Use a custom KiCAD installation path
  1228. Use this when KiCAD is installed outside the standard Windows locations.
  1229. ```powershell
  1230. .\setup-windows-opencode.ps1 -Apply -Scope project -KiCadRoot "D:\Apps\KiCad\10.0"
  1231. ```
  1232. #### Skip install or build steps
  1233. Use these flags when dependencies are already installed or the project is
  1234. already built.
  1235. ```powershell
  1236. .\setup-windows-opencode.ps1 -Apply -Scope project -SkipInstall -SkipBuild
  1237. ```
  1238. #### After applying configuration
  1239. 1. Fully quit OpenCode.
  1240. 2. Start OpenCode again so it reloads `opencode.json`.
  1241. 3. Ask OpenCode to use the `kicad` MCP server and run `check_kicad_ui`.
  1242. #### Disable the OpenCode MCP server
  1243. To disable the server without removing the full configuration, set the entry to
  1244. `enabled: false` and restart OpenCode.
  1245. ```json
  1246. {
  1247. "mcp": {
  1248. "kicad": {
  1249. "enabled": false
  1250. }
  1251. }
  1252. }
  1253. ```
  1254. If OpenCode is running, the MCP server process is managed by OpenCode and
  1255. normally stops when OpenCode exits.
  1256. ### JLCPCB Integration Setup (Optional)
  1257. The JLCPCB integration provides two modes that can be used independently or together:
  1258. **Mode 1: JLCSearch Public API (Recommended - No Setup Required)**
  1259. The easiest way to access JLCPCB's parts catalog:
  1260. - No API credentials needed
  1261. - No JLCPCB account required
  1262. - Access to 2.5M+ parts with pricing and stock data
  1263. - Download time: 40-60 minutes for full catalog (100-part batches due to API limit)
  1264. To download the database:
  1265. ```
  1266. Ask Claude: "Download the JLCPCB parts database"
  1267. ```
  1268. This creates a local SQLite database at `data/jlcpcb_parts.db` (3-5 GB for full 2.5M+ part catalog).
  1269. **Mode 2: Local Symbol Libraries (No Setup Required)**
  1270. Install JLCPCB libraries via KiCAD's Plugin and Content Manager:
  1271. 1. Open KiCAD
  1272. 2. Go to Tools > Plugin and Content Manager
  1273. 3. Search for "JLCPCB" or "JLC"
  1274. 4. Install libraries like `JLCPCB-KiCAD-Library` or `EDA_MCP`
  1275. 5. Use `search_symbols` to find components with pre-configured footprints and LCSC IDs
  1276. **Mode 3: Official JLCPCB API (Advanced - Requires Enterprise Account)**
  1277. For users with JLCPCB enterprise accounts and order history:
  1278. 1. **Get API Credentials**
  1279. - Log in to [JLCPCB](https://jlcpcb.com/)
  1280. - Navigate to Account > API Management (requires enterprise approval)
  1281. - Create API Key and save your `appKey` and `appSecret`
  1282. - Note: This requires prior order history and enterprise account approval
  1283. 2. **Configure Environment Variables**
  1284. Add to your shell profile (`~/.bashrc`, `~/.zshrc`, or `~/.profile`):
  1285. ```bash
  1286. export JLCPCB_API_KEY="your_app_key_here"
  1287. export JLCPCB_API_SECRET="your_app_secret_here"
  1288. ```
  1289. Or create a `.env` file in the project root:
  1290. ```
  1291. JLCPCB_API_KEY=your_app_key_here
  1292. JLCPCB_API_SECRET=your_app_secret_here
  1293. ```
  1294. See [JLCPCB Usage Guide](docs/JLCPCB_USAGE_GUIDE.md) for detailed documentation.
  1295. ## Usage Examples
  1296. ### Basic PCB Design Workflow
  1297. ```text
  1298. Create a new KiCAD project named 'LEDBoard' in my Documents folder.
  1299. Set the board size to 50mm x 50mm and add a rectangular outline.
  1300. Place a mounting hole at each corner, 3mm from the edges, with 3mm diameter.
  1301. Add text 'LED Controller v1.0' on the front silkscreen at position x=25mm, y=45mm.
  1302. ```
  1303. ### Component Placement
  1304. ```text
  1305. Place an LED at x=10mm, y=10mm using footprint LED_SMD:LED_0805_2012Metric.
  1306. Create a grid of 4 resistors (R1-R4) starting at x=20mm, y=20mm with 5mm spacing.
  1307. Align all resistors horizontally and distribute them evenly.
  1308. ```
  1309. ### Routing
  1310. ```text
  1311. Create a net named 'LED1' and route a 0.3mm trace from R1 pad 2 to LED1 anode.
  1312. Add a copper pour for GND on the bottom layer covering the entire board.
  1313. Create a differential pair for USB_P and USB_N with 0.2mm width and 0.15mm gap.
  1314. ```
  1315. ### Autoroute with Freerouting
  1316. Automatically route all unconnected nets using the [Freerouting](https://github.com/freerouting/freerouting) autorouter.
  1317. **Setup (one-time):**
  1318. ```bash
  1319. # 1. Download the Freerouting JAR
  1320. mkdir -p ~/.kicad-mcp
  1321. curl -L -o ~/.kicad-mcp/freerouting.jar \
  1322. https://github.com/freerouting/freerouting/releases/download/v2.0.1/freerouting-2.0.1-executable.jar
  1323. # 2. Runtime — pick ONE:
  1324. # Option A: Docker (recommended, no Java install needed)
  1325. docker pull eclipse-temurin:21-jre
  1326. # Option B: Install Java 21+ locally
  1327. # (Ubuntu/Debian) sudo apt install openjdk-21-jre
  1328. ```
  1329. The autorouter auto-detects which runtime is available (Java 21+ direct, or Docker/Podman fallback).
  1330. ```text
  1331. Check if Freerouting is ready on my system.
  1332. Autoroute the current board using Freerouting with a 5-minute timeout.
  1333. ```
  1334. **Step-by-step workflow:**
  1335. ```text
  1336. 1. Open the project at ~/Projects/LEDBoard/LEDBoard.kicad_pcb
  1337. 2. Check Freerouting dependencies are installed
  1338. 3. Run autoroute with max 10 passes
  1339. 4. Run DRC to verify the autorouted result
  1340. 5. Export Gerbers to the fabrication folder
  1341. ```
  1342. **Manual DSN/SES workflow** (for advanced users or external autorouters):
  1343. ```text
  1344. Export the board to Specctra DSN format.
  1345. # ... run Freerouting GUI or another autorouter externally ...
  1346. Import the routed SES file from ~/Projects/LEDBoard/LEDBoard.ses
  1347. ```
  1348. ### Design Verification
  1349. ```text
  1350. Set design rules with 0.15mm clearance and 0.2mm minimum track width.
  1351. Run a design rule check and show me any violations.
  1352. Export Gerber files to the 'fabrication' folder.
  1353. ```
  1354. ### Using Resources
  1355. Resources provide read-only access to project state:
  1356. ```text
  1357. Show me the current component list.
  1358. What are the current design rules?
  1359. Display the board preview.
  1360. List all electrical nets.
  1361. ```
  1362. ### JLCPCB Component Selection
  1363. **Finding Components with Local Libraries:**
  1364. ```text
  1365. Search for ESP32 modules in JLCPCB libraries.
  1366. Find a 10k resistor in 0603 package from installed libraries.
  1367. Show me details for LCSC part C2934196.
  1368. ```
  1369. **Optimizing Costs with JLCPCB API:**
  1370. ```text
  1371. Search for 10k ohm resistors in 0603 package, only Basic parts.
  1372. Find the cheapest capacitor 10uF 25V in 0805 package with good stock.
  1373. Show me pricing and stock for JLCPCB part C25804.
  1374. Suggest cheaper alternatives to C25804.
  1375. ```
  1376. **Complete Design Workflow:**
  1377. ```text
  1378. I'm designing a board with an ESP32 and need to select components for JLCPCB assembly.
  1379. Search JLCPCB for ESP32-C3 modules.
  1380. Find Basic parts for: 10k resistor 0603, 100nF capacitor 0603, LED 0805.
  1381. For each component, show me the cheapest option with good stock availability.
  1382. Place these components on my board using the suggested footprints.
  1383. ```
  1384. **Database Management:**
  1385. ```text
  1386. Download the JLCPCB parts database (first time setup).
  1387. Show me JLCPCB database statistics.
  1388. How many Basic parts are available?
  1389. ```
  1390. ## Architecture
  1391. ### MCP Protocol Layer
  1392. - **JSON-RPC 2.0 Transport:** Bi-directional communication via STDIO
  1393. - **Protocol Version:** MCP 2025-06-18
  1394. - **Capabilities:** Tools (244), Resources (23)
  1395. - **Tool discovery:** keyword search catalogue indexing 184 tools in 17 categories
  1396. - **Error Handling:** Standard JSON-RPC error codes
  1397. ### TypeScript Server (`src/`)
  1398. - Implements MCP protocol specification
  1399. - Manages Python subprocess lifecycle
  1400. - Handles message routing and validation
  1401. - Provides logging and error recovery
  1402. - **Discovery catalogue:**
  1403. - `src/tools/registry.ts` - Tool categorization and lookup
  1404. - `src/tools/router.ts` - `list_tool_categories`, `get_category_tools`, `search_tools`
  1405. - Search and browse only. It does not gate which tools reach the client, so
  1406. it saves no context; indirect execution was removed in 963a39c because it
  1407. caused schema hallucination. See
  1408. [ROUTER_ARCHITECTURE.md](docs/ROUTER_ARCHITECTURE.md).
  1409. ### Python Interface (`python/`)
  1410. - **kicad_interface.py:** Main entry point, MCP message handler, command routing
  1411. - **kicad_api/:** Backend implementations
  1412. - `base.py` - Abstract base classes for backends
  1413. - `ipc_backend.py` - KiCAD 9.0 IPC API backend (real-time UI sync)
  1414. - `swig_backend.py` - pcbnew SWIG API backend (file-based operations)
  1415. - `factory.py` - Backend auto-detection and instantiation
  1416. - **schemas/tool_schemas.py:** JSON Schema definitions for all tools
  1417. - **resources/resource_definitions.py:** Resource handlers and URIs
  1418. - **commands/:** Modular command implementations
  1419. - `project.py` - Project operations
  1420. - `board.py` - Board manipulation
  1421. - `component.py` - Component placement
  1422. - `routing.py` - Trace routing and nets
  1423. - `design_rules.py` - DRC operations
  1424. - `export.py` - File generation
  1425. - `schematic.py` - Schematic design
  1426. - `library.py` - Footprint libraries
  1427. - `library_symbol.py` - Symbol library search (local JLCPCB libraries)
  1428. - `jlcpcb.py` - JLCPCB API client
  1429. - `jlcpcb_parts.py` - JLCPCB parts database manager
  1430. ### KiCAD Integration
  1431. - **pcbnew API (SWIG):** Direct Python bindings to KiCAD for file operations
  1432. - **IPC API (kipy):** Real-time communication with running KiCAD instance (experimental)
  1433. - **Hybrid Backend:** Automatically uses IPC when available, falls back to SWIG
  1434. - **kicad-skip:** Schematic file manipulation
  1435. - **Platform Detection:** Cross-platform path handling
  1436. - **UI Management:** Automatic KiCAD UI launch/detection
  1437. ## Development
  1438. ### Building from Source
  1439. ```bash
  1440. # Install dependencies
  1441. npm install
  1442. pip3 install -r requirements.txt
  1443. # Build TypeScript
  1444. npm run build
  1445. # Watch mode for development
  1446. npm run dev
  1447. ```
  1448. ### Running Tests
  1449. ```bash
  1450. # TypeScript tests
  1451. npm run test:ts
  1452. # Python tests
  1453. npm run test:py
  1454. # All tests with coverage
  1455. npm run test:coverage
  1456. ```
  1457. ### Linting and Formatting
  1458. ```bash
  1459. # Lint TypeScript and Python
  1460. npm run lint
  1461. # Format code
  1462. npm run format
  1463. ```
  1464. ## Troubleshooting
  1465. ### Server Not Appearing in Client
  1466. **Symptoms:** MCP server doesn't show up in Claude Desktop or Cline
  1467. **Solutions:**
  1468. 1. Verify build completed: `ls dist/index.js`
  1469. 2. Check configuration paths are absolute
  1470. 3. Restart MCP client completely
  1471. 4. Check client logs for error messages
  1472. ### Python Module Import Errors
  1473. **Symptoms:** `ModuleNotFoundError: No module named 'pcbnew'`
  1474. **Solutions:**
  1475. 1. Verify KiCAD installation: `python3 -c "import pcbnew"`
  1476. 2. Check PYTHONPATH in configuration matches your KiCAD installation
  1477. 3. Ensure KiCAD was installed with Python support
  1478. ### Tool Execution Failures
  1479. **Symptoms:** Tools fail with unclear errors
  1480. **Solutions:**
  1481. 1. Check server logs: `~/.kicad-mcp/logs/kicad_interface-<pid>.log` (one file per server process)
  1482. 2. Verify a project is loaded before running board operations
  1483. 3. Ensure file paths are absolute, not relative
  1484. 4. Check tool parameter types match schema requirements
  1485. ### Windows-Specific Issues
  1486. **Symptoms:** Server fails to start on Windows
  1487. **Solutions:**
  1488. 1. Run automated diagnostics: `.\setup-windows.ps1`
  1489. 2. Verify Python path uses double backslashes: `C:\\Program Files\\KiCad\\10.0`

Lines 2,001–2,128 are not shown. The link to the file on GitHub has every line.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.