needhuman-mcp

MCP server for NeedHuman — Human-as-a-Service API for AI agents.

When your agent hits a step it requires any real human with a browser — accepting terms of service, creating an account, completing identity verification, submitting web forms — it calls NeedHuman. A human (yes, it's basically me in the beginning) completes the task, submits proof, and the agent continues.

Option A — Remote HTTP (zero install):

Connect directly to the hosted MCP endpoint — no npm, no local server:

URL: https://needhuman.ai/mcp
Transport: Streamable HTTP
Auth: Bearer YOUR_KEY (in Authorization header)

Works with Claude.ai, Smithery, and any MCP client that supports HTTP transport.

Option B — npx (local stdio):

Add to your MCP client config (e.g. ~/.claude/settings.json or .cursor/mcp.json):

{
  "mcpServers": {
    "needhuman": {
      "command": "npx",
      "args": ["-y", "@needhuman/mcp-server"],
      "env": {
        "NEEDHUMAN_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Option C — one-line install (Claude Code):

curl -sf "https://needhuman.ai/api/v1/setup?key=YOUR_KEY" | bash

Writes ~/.needhuman/mcp-server.ts and adds NeedHuman to ~/.claude/settings.json.

Get an API key (3 free tasks, no signup):

curl -X POST https://needhuman.ai/api/v1/keys/register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}'

| Tool | Description | |------|-------------| | need_human | Submit a task for a human to complete. Returns a task ID. | | check_task_status | Poll a task by ID. Returns status, result, and proof. | | list_tasks | List all tasks for the current API key. |

Add this to your agent's system prompt:

When you encounter a task that requires a real human with a browser
and you cannot complete it yourself, call the need_human tool.

Do not describe what a human should do. Do not suggest