Two ways to design

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?

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:

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

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

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.

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.