# heypcb-mcp [Health: Active]

**Category:** 📐 Architecture & Design  
**Repository:** https://github.com/HeyPCB/heypcb-mcp  
**GitHub Stars:** 26  
**npm Downloads (last month):** 526  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/heypcb-mcp

## Description
HeyPCB for AI agents: an MCP server that gives Claude Code, Codex, Cursor and claude.ai a PCB engineer. npx -y @heypcb/mcp

## Tools
Capabilities this server exposes over MCP:

- **whoami** — Your HeyPCB account, plan, balance and what can run. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **list_projects** — Your HeyPCB boards: id, name, last update, web link. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **create_project** — Create an empty HeyPCB board project. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **build_board** — Design a whole PCB from a plain-language brief: schematic, parts, placement, routing and checks. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **ask_inky** — One turn of Inky, HeyPCB's design agent, on a project: a question or an edit. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **wait_for_turn** — Wait for a running Inky turn and return its result. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **answer_decision** — Answer a decision Inky asked for (for example approve the layout). (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **get_board** — Board facts: layers, size, parts, nets, routed %, DRC/ERC counts, fab readiness, web link. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **get_board_image** — A picture of the PCB (top or bottom), a schematic page or the 3D view. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **check_board** — Run DRC, ERC and the placement check, the full verification, or the fab check, with findings. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **route_board** — Autoroute the board and return the result. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **place_parts** — Re-place the board's parts. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **export** — Gerbers, KiCad project, BOM, pick-and-place or STEP as a short-lived download link. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **read_design** — Read the design or a schematic/board file's text for inspection. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **undo** — Undo the last change to a project. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **estimate** — The price of an operation before running it. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **search_parts** — Find real, orderable parts: LCSC stock and price, verified footprints, KiCad symbols. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **get_part** — A part's pins and facts: an LCSC part card, a KiCad symbol's pins, or a part on the board. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **add_parts** — Add parts to the board's design; the board places them. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **remove_parts** — Delete parts from the design and the board. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **set_part_value** — Change one part's value in place. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **source_parts** — Give every unsourced part an orderable LCSC part. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **connect** — Connect pins (REF.PIN) into named nets. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **disconnect** — Remove pins from every net they are on. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **list_blocks** — HeyPCB's proven circuit blocks (USB-C power, regulators, MCU modules…). (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **add_block** — Add a proven circuit block to the design. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **set_net_class** — Set a net class: width, clearance, current, impedance, differential pairs. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **rename_net** — Rename a net. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **set_no_connect** — Toggle a no-connect flag on a pin. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **get_netlist** — Every net with its pins, class and drivers. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **get_design_summary** — The design in one compact read: parts, nets, counts, unsourced parts. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **get_schematic** — One schematic page as text, with the page list. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **get_capable_pins** — Which MCU pins can carry a function (UART, I2C, SPI, PWM…) and are free. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **set_board_outline** — Set the board's outline in mm (rect, rounded, circle, polygon…), with corner mounting holes. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **set_board_rules** — Set the copper layers (2 or 4) and the design rules, e.g. JLCPCB's. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **move_part** — Move parts on the board: x/y, a shift, beside a pin, against an edge; refused with where it fits. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **lock_parts** — Pin parts where they are so place_parts keeps them. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **unlock_parts** — Release locked parts. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **add_ground_pour** — Pour the GND plane once routing is finished. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **add_text** — Write text on the board (silkscreen, copper or mask). (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **add_mounting_hole** — Put a screw hole (M2–M4) on the board. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **get_board_layout** — The layout in one read: outline, layers, rules, every part's place, rotation, side and box. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **preview_board** — A CAD view of the board: chosen layers, highlighted nets and parts, open connections, cropped. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **inspect_net** — A net measured: status, copper per layer, vias, every open connection pin to pin. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **inspect_part** — A part measured: place, edge gaps, neighbours, open pins, the nearest cap to each supply pin. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **check_placement** — Grade the placement: decoupling, crystals, connectors at edges; each finding names its fix. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **set_placement_rules** — Say where parts go: edges, locks, caps by a pin, signal chains, rings and grids. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **preview_placement** — Plan a re-place on a copy and show it before anything moves. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **apply_placement** — Land a previewed placement plan exactly, as one undoable change. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **list_history** — Every change the board can go back through, and what redo can put back. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **restore_board** — Put the board back to any point in its history, in one guarded call. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **redo** — Put back changes undo or restore_board took back. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **save_checkpoint** — Save the whole board under a label, past the 50 changes the history keeps. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **delete_checkpoint** — Delete a saved checkpoint. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **rip_up_net** — Delete a net's tracks and vias so it can be routed again. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **add_pour** — Pour copper on any net and layer, once routing is finished. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **remove_pour** — Take a copper pour off the board. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **add_keepout** — Keep an area clear of tracks, vias, pads, pours or parts. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **stitch_vias** — Stitch a net's pours together with a grid of vias. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **tune_lengths** — Match lengths of a bus or a differential pair with meanders, kept only when DRC holds. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **check_routing** — Grade routed copper against pairs, matched lengths and impedance the net classes state. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **tidy_silkscreen** — Re-place every silkscreen designator beside its part, clear of pads and openings. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **rename_part** — Rename a designator everywhere: design, nets, schematic and board. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **tidy_schematic** — Re-lay the schematic's hand-placed symbols with HeyPCB's own layout. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **get_guide** — The playbook for designing a board with these tools yourself. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **stop_turn** — Stop a running Inky turn at its next step. (HeyPCB is not connected yet: calling this explains how to sign in. The full description arrives once it is.)
- **open_kicad_project** — Work on a KiCad project on this computer with HeyPCB's tools, keeping it a normal KiCad project in its own folder. The first call binds the folder to a new HeyPCB project: it UPLOADS the project's files (the board, every schematic sheet, the .kicad_pro, .kicad_dru, lib tables and project-local libraries — never 3D models, backups or anything .heypcbignore names) and writes .heypcb/workspace.json. Tell the user their files go to HeyPCB. Later calls reuse the binding and sync both ways. From then on, every HeyPCB tool called with the returned `project` id syncs this folder: changes saved here go up before the call; files a call changes come back after it (the old ones backed up in .heypcb/backup/), and the result's local_files_changed says what to reload in KiCad. A file saved in KiCad while a call ran is never overwritten: HeyPCB's version lands beside it as <file>.heypcb-new and syncing waits for `on_conflict`. Free. Returns `project` (use it as `project` in the other tools), the web link and what synced.
- **upload_kicad_project** — Upload a KiCad project from this computer to HeyPCB as a NEW, separate HeyPCB project (a copy: nothing syncs back). To work on a project in its folder, use open_kicad_project instead. `path` is the project's folder (the one holding its .kicad_pro / .kicad_pcb) or the .kicad_pro / .kicad_pcb / .kicad_sch file itself; ~ is your home folder. It sends the board, the root schematic and every sub-sheet it names, the .kicad_pro, .kicad_dru, sym-lib-table / fp-lib-table and the project-local libraries they name — never 3D models, backups, .kicad_prl or what .heypcbignore names — at most 50 MB. Free. Returns the new project's id (use it as `project` in the other tools), its web link, and the files sent. Each call makes a new project.
- **save_export** — Download a HeyPCB project's manufacturing or design files and save them into a folder on this computer. kind: gerbers (fab zip with drill files), kicad (the KiCad project as a zip), bom (CSV), cpl (pick-and-place CSV), step (3D model). `dir` is created if it is inside your home folder; a folder elsewhere must already exist and be writable. An existing file is kept: the new one gets -2, -3… unless `overwrite` is true. Free (on a trial, design-file downloads count as on the web). Returns the saved file's absolute path.
- **check_local** — Run KiCad's own DRC (kind drc, on the .kicad_pcb) or ERC (kind erc, on the root .kicad_sch) on the project here with kicad-cli: free, no network, nothing uploaded. A fast pre-check after edits; check_board on HeyPCB stays the full verification (placement, power, fab readiness). Needs KiCad 8 or newer installed. Returns passed, counts {errors, warnings, unconnected} and findings [{severity, type, message, where:[{text, x, y}]}] (mm), errors first.
- **export_local** — Make manufacturing files from the project here with KiCad's kicad-cli: free, no network. kind: gerbers (a zip of the Gerbers, with the board's own plot settings, and the drill files), bom (CSV from the schematic), cpl (pick-and-place CSV, mm, both sides), step (3D model). `dir` defaults to the project's exports/ folder; an existing file is kept (the new one gets -2, -3…) unless `overwrite` is true. Needs KiCad 8 or newer. For HeyPCB's own fab-checked files use save_export.
- **restore_local** — Put back the project files a sync backed up before HeyPCB's changes replaced them (.heypcb/backup/<revision>/). Without `revision` it lists the backups. What is there now is backed up first, so a restore can be undone the same way; the restored files go to HeyPCB with the next sync. Free, local.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "heypcb-mcp": {
    "command": "npx",
    "args": ["-y","@heypcb/mcp"]
  }
}
```

## Documentation

## What heypcb-mcp does

heypcb-mcp exposes HeyPCB’s PCB engineering capabilities to MCP-compatible agents. It supports two design styles: an agent can request a complete board through high-level operations such as `build_board`, `get_board`, `check_board`, and `export`, or it can construct the design step by step with parts, circuit blocks, connections, board rules, placement, copper features, and routing controls.

The package also works with KiCad projects stored on the local computer. It can bind a project folder to a HeyPCB project, upload a separate copy, synchronize edits, run local KiCad checks, and write fabrication outputs into a chosen directory.

## How it works

The hosted service is available at `https://api.heypcb.ai/mcp` over Streamable HTTP and uses OAuth sign-in in a browser. The local package is started with `npx -y @heypcb/mcp` and communicates over stdio. It forwards HeyPCB tools to the remote service and adds file-oriented operations that need access to the computer.

When a local folder is opened, the first sync creates a HeyPCB project and records the association in `.heypcb/workspace.json`. Later calls upload local changes before running and bring changed design files back afterward. Previous files are backed up under `.heypcb/backup/<revision>/`. If both KiCad and HeyPCB changed a file, the incoming version is written as a `.heypcb-new` file until the agent chooses whether to keep the local or HeyPCB version. `.heypcbignore` can exclude files from uploads.

## Setup and configuration

The local package requires Node.js 18 or newer. Install nothing separately for the main server; run it with `npx`. Authenticate either with `npx @heypcb/mcp login`, which stores credentials for the computer, or set a personal `HEYPCB_API_KEY`. The server can also report the signed-in account with `status` and remove the sign-in with `logout`.

`HEYPCB_MCP_URL` changes the remote MCP endpoint, and `HEYPCB_API_BASE` controls the API host used for sign-in and local operations. Both have defaults. The hosted endpoint can be added directly to clients that support Streamable HTTP; the local command can be configured as a stdio MCP server.

Local DRC, ERC, and export operations additionally require KiCad 8 or newer, with `kicad-cli` available on `PATH` or in KiCad’s standard installation directory.

## Tools and capabilities

- Build complete boards or inspect existing board state.
- Search and retrieve parts, add parts and circuit blocks, connect nets, and read netlists.
- Set outlines and design rules, move or lock parts, define placement rules, and add ground pours.
- Inspect parts and nets, preview layers and highlighted connections, and check placement.
- Manage copper with pours, keepouts, via stitching, and net rip-up operations.
- Run board verification; findings identify the tool call associated with a fix.
- Review board history, restore earlier states, and redo changes.
- Open or upload KiCad projects, synchronize edits, and restore backed-up local files.
- Save or locally generate Gerbers, drill files, BOMs, pick-and-place files, KiCad projects, and STEP output.

The local `install_parts` operation refuses before writing because the required parts-assets API is not available. HeyPCB parts are not yet installed into a project’s own libraries through the local workflow.

_Full upstream README: https://allmcps.com/mcp/heypcb-mcp/readme_