zap-pcb-mcp

KiCad PCB autorouter for AI agents: MCP server, HTTP API and CLI, with a JSON manufacturability report (DRC, shorts, JLCPCB capability, copper heat).

zap-pcb-mcp is the stdio MCP server for Zap!, a hosted auto-router by mutual. You give it a placed .kicad_pcb (with its .kicad_pro); it returns the same board with tracks, vias and copper pours added, plus a report of what is still wrong and where. Node 18 or newer. The board is routed on the Zap! service, not on your machine.

Early access: every routed board must be reviewed by an engineer, and KiCad's DRC run, before fabrication.

Quick start

Claude Code

claude mcp add zap -e ZAP_API_KEY_FILE=$HOME/zap-key.txt -- npx -y zap-pcb-mcp

Restart the agent session: the tools appear only after the restart.

Claude Desktop, Cursor and other MCP clients

{
  "mcpServers": {
    "zap": {
      "command": "npx",
      "args": ["-y", "zap-pcb-mcp"],
      "env": { "ZAP_API_KEY_FILE": "/absolute/path/to/zap-key.txt" }
    }
  }
}

Claude Desktop: claude_desktop_config.json. Cursor: ~/.cursor/mcp.json or .cursor/mcp.json in the project.

The API key

Sign in at https://zap.mutual.solutions/auth/login and create an API key on your account page. Save it as ~/zap-key.txt and run chmod 600 ~/zap-key.txt. The server reads the key from the environment only, in this order:

variable	meaning
ZAP_API_KEY	the key itself
ZAP_API_KEY_FILE	path to a file holding the key (default ~/.config/zap/key)
ZAP_URL	service address, default https://zap.mutual.solutions; must be https

The key is never taken from tool arguments and never written to tool output or logs. The server warns when the key file is readable by other users. Redirects are never followed, so the key is only sent to ZAP_URL.

No key: the free trial

Without a key, the try_route_board tool routes one small board with no sign-up: at most 300 pads, 2 or 4 copper layers, 2 trial jobs per network address per UTC day, stable router only. Every tool that needs a key answers, when none is set, with how to get one and that the trial exists.

claude mcp add zap -- npx -y zap-pcb-mcp

Then ask your agent to route a board, for example: "Route ~/boards/myboard.kicad_pcb with Zap!".

Tools

The names, arguments and answers match the single-file Python server zap_mcp.py, so the guides at https://zap.mutual.solutions/agents.md apply to both.

tool	key	what it does
check_board	yes	Pre-flight check (seconds, no routing, no job quota): every problem that would stop the job (blockers) and what would weaken it (warnings), with references, positions and the KiCad fix.
route_board	yes	Check, submit, wait, then save BOARD.routed.kicad_pcb, the full report BOARD.routed.zap-report.json, one SVG per copper layer and copies of BOARD.kicad_pro / .kicad_dru; then delete the server copy. An EasyEDA file with one PCB, a Standard PCB document (.json) or a Pro 3.x+ project (.epro, .epro2, .eprj), is sent alone and comes back as BOARD.routed.json / .epro (same format: your file plus only Zap!'s copper; rebuild the pours in EasyEDA before its DRC). If the reader found something it may have lost or changed, the board is still routed and easyeda_conversion_findings lists it. Projects saved by EasyEDA Pro 2.x are refused for now.
try_route_board	no	The same as route_board on the free trial (limits above). The trial deletes the job's files on the server right after the routed board is downloaded.
get_report	yes*	Every missing connection, design-rule error, JLC violation, hot spot and leftover copper, with position (mm), layer, net and what to do in KiCad.
get_job	yes*	Status and result numbers of a job; download_to saves the routed board.
list_jobs	yes	The key's last 50 jobs.
delete_job	yes	Cancel a queued or running job, or delete a finished job's files.
send_feedback	yes	Send the user's opinion to the Zap! team, only after the user approved the exact text (user_approved: true).
board_snapshot	yes	PNG of one square area (at most 40 mm) of a routed board with issues marked, returned as an image.
delete_snapshot	yes	Delete a picture the user does not want attached.

* For a trial job, get_job and get_report work without a key in the same server session; after a restart pass the try_token that try_route_board returned.

check_board, route_board and try_route_board take every upload option of the API with the same name and default: project_path, rules_path, currents_path or currents, router (not on the trial), keep_existing, strip_existing, fab_floor, signal_width_mm, via_diameter_mm, via_drill_mm, vias_in_pads, ground_pour, size_rails_from_current, effort, minutes, consent_training. Boards are sent gzip-compressed.

HTTP API

Base URL https://zap.mutual.solutions, header Authorization: Bearer <key>. The key goes to curl as a header file, so it never appears in a command line:

This is the beginning of the README. Read the rest at the original. Read the full README ↗