Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@proxyhuman/mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@proxyhuman/mcp

ProxyHuman MCP server — let an AI agent ask a human for help with a browser-based task (signing in, solving a captcha, completing 2FA, reading an OTP from email/SMS, entering payment info, picking a subjective option) and get back a structured log of what the human did.

Pairs with the proxyhuman Agent Skill at aidenlabsdotdev/skills, installed via npx skills add aidenlabsdotdev/skills --skill proxyhuman --agent <harness> — the skill is the SKILL.md that tells the agent when to reach for this MCP.

Install

# 1. Install the MCP server (this package)
npm i -g @proxyhuman/mcp

# 2. Sign up — a Clerk-issued long-lived API key is saved to
#    ~/.proxyhuman/config.json. Verification OTP is sent to your email.
proxyhuman sign-up --email you@example.com
proxyhuman verify <code-from-email>

# 3. Register the MCP in your harness:
claude mcp add proxyhuman -- proxyhuman-mcp
#   or for Hermes / Codex / Cursor / etc., the harness-specific equivalent

# 4. Install the proxyhuman Agent Skill — this is the SKILL.md that tells
#    the agent *when* to reach for the MCP (sign-ins, captchas, OTPs, …).
#    Without it the tools are registered but the agent won't know to use them.
npx skills add aidenlabsdotdev/skills --skill proxyhuman --agent claude-code
#   --agent hermes-agent | codex | cursor | cline | … (20+ supported)

The npm i -g postinstall fetches a WHIP-capable ffmpeg 8.1 (BtbN on Linux/ Windows, martin-riedl.de on macOS) and stages it in the package's bin/. ~30–200 MB one-time download per platform, used by the MCP to publish the browser's screencast to Cloudflare Realtime SFU.

Two bins

Binary	Purpose
`proxyhuman-mcp`	The stdio MCP server. Register this with your harness.
`proxyhuman`	CLI for `sign-up`, `verify`, `me`, and `config show/get/set`.

MCP tools

Tool	Description
`open_browser_handoff_link`	Mints a viewer URL that mirrors the agent's Chrome to the human's phone/desktop. Does NOT notify — your harness owns the messaging channel.
`wait_for_human_handback`	Blocks until the human clicks "return control to agent" (or timeout). Returns the structured action log and final page URL.

Config resolution (priority order)

Setting	Order
`api_key`	tool arg → `PROXYHUMAN_API_KEY` env → `~/.proxyhuman/config.json`
`api_url`	tool arg → `PROXYHUMAN_API` env → `~/.proxyhuman/config.json` → `https://api.proxyhuman.ai`
`cdp_target`	tool arg → `PROXYHUMAN_CDP` env → `~/.hermes/config.yaml::browser.cdp_url` → probe localhost ports → default

How it talks to the rest of the system

agent → @proxyhuman/mcp (this) ──┐
                                  │ HTTP/WS
                                  ▼
                           api.proxyhuman.ai
                          (Worker + Durable Object)
                                  │
                                  ▼
                       Cloudflare Realtime SFU
                                  ▲
                                  │ WebRTC (UDP)
                                  ▼
                       human's phone/desktop
                          (app.proxyhuman.ai)

@proxyhuman/mcp runs on the customer's machine (it needs CDP access to a local Chrome and a local ffmpeg). Everything else is hosted on Cloudflare.

Source

Developed by Aiden Labs. This repo (aidenlabsdotdev/proxyhuman-mcp) is what npm publishes from — issues and PRs welcome here.