claudeers.
// MCP Servers

heypcb-mcp

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

// MCP Servers[ cli ][ api ][ desktop ][ web ][ claude ]#claude#ai-agents#autorouter#claude-code#codex#cursor#eda#electronics#mcp-servers◷ MIT$open-sourceupdated 30 days ago
Actively maintained
100/100
last commit 16 days ago
last release 29 days ago
releases 5
open issues 0

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up heypcb-mcp (mcp-stdio project) into my current project.
Found on https://claudeers.com/heypcb-mcp
Repo: https://github.com/HeyPCB/heypcb-mcp
Homepage/docs: https://heypcb.ai/mcp
Detected install method: mcp-stdio → claude mcp add heypcb-mcp -- npx -y @heypcb/mcp
Category: mcp-servers. Platforms: cli, api, desktop, web.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
active; community-verified: false. Confirm the source before running anything.
// or install directly (mcp-stdio)
claude mcp add heypcb-mcp -- npx -y @heypcb/mcp
// or clone
git clone https://github.com/HeyPCB/heypcb-mcp

// compatibility

Platformscli, api, desktop, web
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageTypeScript

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

@heypcb/mcp

HeyPCB for AI agents. Design real KiCad boards from Claude Code, Codex, Cursor or Claude Desktop.

Website · Quick start · Local server · Billing · Troubleshooting


Two ways to design

You sayYour agent calls
Let HeyPCB design it"Build a USB-C powered board for …"build_board, get_board, check_board, export. HeyPCB's server does the engineering: Inky's design agent, parts, placement, routing, DRC/ERC and fab checks.
Let your agent design it"Add an LDO and wire it to the MCU"Parts and blocks: search_parts, get_part, add_parts, add_block, connect, get_netlist. Layout: set_board_outline, set_board_rules, move_part, lock_parts, add_ground_pour, get_board_layout. Then check_board until the board is fab-ready. Each finding names the call that fixes it (fixWith).

Quick start

HeyPCB runs the MCP server for you at https://api.heypcb.ai/mcp (Streamable HTTP, OAuth sign-in in your browser). Nothing to install:

claude mcp add --transport http heypcb https://api.heypcb.ai/mcp

Codex and claude.ai (as a custom connector) take the same URL.

Which one do I need?

Remote serverLocal server (this package)
InstallnothingNode.js 18+
All HeyPCB tools✅✅
Upload a KiCad project from your disk❌✅ upload_kicad_project
Save Gerbers, BOM, CPL, STEP to a folder❌✅ save_export

Use the remote server unless you need one of the two local tools.

The local server (this package)

npx -y @heypcb/mcp runs a small MCP server on your computer (stdio). It passes every HeyPCB tool through to the remote server unchanged, with the same names, schemas, results, progress and cancellation. It has no design logic of its own. It adds two tools that need your files:

ToolWhat it does
upload_kicad_projectZips a KiCad project folder on this computer (board, schematic hierarchy, .kicad_pro, .kicad_dru, library tables and project-local libraries, but not 3D models, backups or .kicad_prl; at most 50 MB) and imports it as a new HeyPCB project. Returns the project id and its web link.
save_exportSaves Gerbers, the KiCad project, BOM, pick-and-place (CPL) or STEP into a folder here, atomically, and returns the file's path.

It needs Node.js 18 or newer and nothing else. Everything it uses is bundled into one file.

1. Sign in (once per computer)

Option A: sign in with a code

npx @heypcb/mcp login

It opens heypcb.ai/connect and shows a code; check the page shows the same code and approve. The sign-in is stored in ~/.config/heypcb/credentials.json (%APPDATA%\heypcb\credentials.json on Windows), readable only by you. A running server picks it up on its next call, without a restart.

Option B: use a personal key

Make one in heypcb.ai → Settings → Devices & API keys and give it to the server as HEYPCB_API_KEY (examples below). A key is used instead of a stored sign-in while it is set.

[!TIP] Without either, the server still starts, and every tool answers with these two ways to sign in.

2. Add it to your agent

Claude Code

claude mcp add heypcb -- npx -y @heypcb/mcp
# or with a personal key instead of `login`:
claude mcp add heypcb -e HEYPCB_API_KEY=hpcb_pk_… -- npx -y @heypcb/mcp

Cursor

Or add it by hand to .cursor/mcp.json in your project (or ~/.cursor/mcp.json):

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

Codex

In ~/.codex/config.toml:

[mcp_servers.heypcb]
command = "npx"
args = ["-y", "@heypcb/mcp"]
# env = { HEYPCB_API_KEY = "hpcb_pk_…" }

Claude Desktop

In claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "heypcb": {
      "command": "npx",
      "args": ["-y", "@heypcb/mcp"],
      "env": { "HEYPCB_API_KEY": "hpcb_pk_…" }
    }
  }
}

3. Try it

Ask your agent, for example:

  • "Upload my KiCad project at ~/boards/sensor to HeyPCB and run the full check."
  • "Save the Gerbers and BOM for that project into ~/boards/sensor/fab."

Commands

npx -y @heypcb/mcp          run the MCP server on stdio (what your agent runs)
npx @heypcb/mcp login       sign in with a code (--no-browser prints the link only)
npx @heypcb/mcp logout      sign out here and end that sign-in on HeyPCB
npx @heypcb/mcp status      who this computer is signed in as
Environment variables
VariableMeaning
HEYPCB_API_KEYA personal key (hpcb_pk_…). Used instead of a stored sign-in.
HEYPCB_MCP_URLThe remote server. Default https://api.heypcb.ai/mcp.
HEYPCB_API_BASEThe API host for sign-in and the local tools. Default: the MCP URL's host, and it must be that host.
HEYPCB_WEB_BASEWhere project links point. Default https://heypcb.ai.
HEYPCB_CONFIG_DIRWhere the sign-in is stored.
HEYPCB_MCP_TIMEOUT_MSHow long one remote call may run without progress. Default 10 minutes.

What it does with your computer

  • Reads files only when you call upload_kicad_project, and only the project's own files listed above. A file or link that leads outside the project folder stops the upload; nothing partial is sent.
  • Writes files only when you call save_export: inside your home folder (it creates missing folders), or into an existing folder elsewhere that you can write to. It never follows a link out of your home folder, never writes into folders that hold keys (~/.ssh, ~/.aws, …), never overwrites a file unless you pass overwrite: true, and writes through a temp file it renames into place.
  • Your sign-in is only ever sent to the API host it was issued by, over https (plain http only to localhost). Refreshes are coordinated between every copy of the server running on your computer, so two agents never spend the same refresh token.

Billing

Tools cost what the same work costs on heypcb.ai, from the same account and wallet. estimate prices an operation before it runs; whoami shows the balance. The parts and circuit tools your own agent designs with are free (rate-limited per account; whoami says the limits).

Troubleshooting

ProblemFix
Every tool says to sign inRun npx @heypcb/mcp login, or set HEYPCB_API_KEY. Check with npx @heypcb/mcp status.
Claude Desktop can't find npxIt starts servers with a short PATH. Put the full path from which npx in command.
Running npx @heypcb/mcp in a terminal prints a hint and waitsThat's expected: your agent starts the server, not you. Add it to your agent as shown above.
A long call stops with remote_timeoutIt may still be running on HeyPCB. Read its state (wait_for_turn for a turn, get_board for a board) before calling it again, or raise HEYPCB_MCP_TIMEOUT_MS.

Source

The source is at https://github.com/HeyPCB/heypcb-mcp. Issues and pull requests are welcome there; see CONTRIBUTING.md, and send security reports as described in SECURITY.md. Releases are mirrored there from HeyPCB's own repository. That GitHub repository's CI then publishes each release to npm with provenance, so npm links each version to the commit and the build that made it.

Development

The package has its own pnpm lockfile and is its own workspace root.

pnpm install --ignore-workspace --frozen-lockfile
pnpm run typecheck
pnpm run test          # node --test against a fake HeyPCB host
pnpm run build         # dist/cli.js, one bundled file
pnpm run test:smoke    # the built file over stdio

Releasing: bump version in package.json and src/version.ts (a test holds them equal). When that commit reaches main in heypcb-mcp, its CI publishes it to npm, with provenance, if that version is not on npm yet.

License

MIT; see LICENSE. The bundled packages' notices are in dist/THIRD-PARTY-NOTICES.txt in the published package.

// faq

What is heypcb-mcp?

HeyPCB for AI agents: an MCP server that gives Claude Code, Codex, Cursor and claude.ai a PCB engineer. npx -y @heypcb/mcp. It is open-source on GitHub.

Is heypcb-mcp free to use?

heypcb-mcp is open-source under the MIT license, so it is free to use.

What category does heypcb-mcp belong to?

heypcb-mcp is listed under mcp-servers in the Claudeers registry of Claude-compatible tools.

37 views
★ 35 stars
unclaimed
updated 30 days ago

// embed badge

heypcb-mcp on Claudeers
[![Claudeers](https://claudeers.com/api/badge/heypcb-mcp.svg)](https://claudeers.com/heypcb-mcp)

// retro hit counter

heypcb-mcp hit counter
[![Hits](https://claudeers.com/api/counter/heypcb-mcp.svg)](https://claudeers.com/heypcb-mcp)

// reviews

// guestbook

0/500

// related in MCP Servers

🔓

f.k.a. Awesome ChatGPT Prompts. Share, discover, and collect prompts from the community. Free and open source — self-host for your organization with complete…

// mcp-serversf/⟨HTML⟩★ 175,627◷ NOASSERTION[ claude ]
🔓

A cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io

// mcp-serversfarion1231/⟨Rust⟩★ 151,540◷ MIT[ claude ]
🔓

🪨 why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman

// mcp-serversJuliusBrussee/⟨JavaScript⟩★ 117,780◷ MIT[ claude ]
🔓

An open-source AI agent that brings the power of Gemini directly into your terminal.

// mcp-serversgoogle-gemini/⟨TypeScript⟩★ 108,744◷ Apache-2.0[ claude ]
→ see how heypcb-mcp connects across the ecosystem