MCP server

Drive bitHuman from any AI agent. The bitHuman MCP server is built into the CLI (`bithuman mcp`) and exposes the platform as Model Context Protocol tools for Claude Desktop, Claude Code, Cursor, and other MCP clients.

The bitHuman MCP server lets any Model Context Protocol client — Claude Desktop, Claude Code, Cursor, and others — call bitHuman directly as tools. Ask your agent to “make an avatar that explains our pricing and have it speak this script,” and it can generate the agent, synthesize the speech, and mint an embed token without you writing any glue code.

It’s built into the bitHuman CLI — just run bithuman mcp. The cloud tools are a thin wrapper over the REST API — each tool maps to one documented endpoint — plus a few local tools that inspect your install and model files. Not every endpoint has a tool yet: talking video (POST /v1/video/generate), model add (POST /v1/agent/{code}/models), and the knowledge API (/v1/knowledge) are HTTP-only for now.

Note — one server. bithuman mcp, inside the CLI, is the bitHuman MCP server. A standalone bithuman-mcp package was published on PyPI until 2026-09-15 and has been removed, so asking pip for that name now fails outright. If you registered that command with your MCP client, change it to bithuman mcp.

bithuman is the only bitHuman package on PyPI, and it is the Python library — not the CLI and not the MCP server. The CLI that carries this server installs from install.bithuman.ai or Homebrew.

Install and register

The server is the CLI. Install the CLI, then point your MCP client at it:

bithuman mcp            # the server itself — this is what an MCP client launches
bithuman mcp tools      # print the tool surface and exit

Client configuration is one entry:

{ "command": "bithuman", "args": ["mcp"] }

bithuman mcp tools on cli-v2.6.20 prints 28 tools — 6 local and 22 cloud. The local six (version, doctor, inspect_model, list_showcase, pull, render) work against your own install and model files; the rest are the REST API below. Authenticate once with bithuman login, as for any other command.

Tools

Cloud tools — wrap the REST API (and platform status):

Local tools — no network; inspect your install and local files:

Setup

Install the bitHuman CLI:

curl -fsSL https://raw.githubusercontent.com/bithuman-product/homebrew-bithuman/main/install.sh | sh

macOS Apple Silicon and Linux x86_64 — more on the CLI page.

Version check for model / version support: bithuman --version must report CLI 2.4.1 or newer. The current release is well past that (which version that is), so a fresh install is already there — but an install still on 2.4.0 has no model parameter on generate_agent, and every creation uses the platform default model. Until your install reports 2.4.1+, upgrade (brew upgrade bithuman-cli, or re-run install.bithuman.ai). There is no pip alternative: the standalone server was removed from PyPI on 2026-09-15.

Authenticate once with bithuman login (or export BITHUMAN_API_SECRET from the Developer Dashboard). The server resolves your credential automatically — env → OS keychain → ~/.bithuman/config — so you usually don’t pass it per-client. Then register bithuman mcp:

Claude Code

claude mcp add bithuman -- bithuman mcp

If you haven’t run bithuman login, pass the secret inline: claude mcp add bithuman -e BITHUMAN_API_SECRET=sk_your_secret -- bithuman mcp.

Claude Desktop / generic JSON config

{
  "mcpServers": {
    "bithuman": {
      "command": "bithuman",
      "args": ["mcp"]
    }
  }
}

Cursor

In Settings → MCP → Add new MCP server, or in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "bithuman": {
      "command": "bithuman",
      "args": ["mcp"]
    }
  }
}

If you haven’t signed in with bithuman login, add an "env": { "BITHUMAN_API_SECRET": "sk_your_secret" } block to the config.

Verify the connection

After adding the server, your client should list a bithuman tool group. The quickest confirmation is to ask the agent:

Use the bithuman tools to validate my API secret.

It calls validate_api_secret and should reply with {"valid": true}. If you get valid: false, re-check your credential (bithuman whoami); if no bithuman tools appear at all, confirm bithuman is on your PATH and restart the client.

Using it

You drive everything in natural language — the agent picks the right tools and chains them. A few worked examples:

Stand up a talking avatar and embed it

Generate an avatar of a friendly fitness coach, wait until it’s ready, then give me an embed token for it.

The agent calls generate_agent, polls get_agent_status until ready (a few minutes for first-generation models; roughly 45 minutes to 1.5 hours for the second generation), then create_embed_token and hands you the JWT for the embed widget.

Create a photoreal Essence 2 agent (CLI 2.4.1+ / bithuman-mcp 0.3.4+)

Create an essence-2 avatar from this photo: https://…/portrait.jpg — a helpful retail assistant. Tell me the agent id and poll until it’s ready.

The agent calls generate_agent with model: "essence-2" (equivalently model: "essence", version: "v2") — 500 credits, and the input must be a photorealistic human subject (else the API rejects it 422 before billing, see the subject gate) — then polls get_agent_status. Expect the lip_sync step to run ~25–40 minutes while the identity trains. Creation is image-only: never pass video. The bithuman-mcp 0.3.4 schema still listed a legacy video field — the API rejects it with 400 VIDEO_INPUT_NOT_SUPPORTED — and bithuman-mcp 0.3.5 and the CLI 2.4.1+ server have both dropped it.

Turn a script into speech

List the female voices, then read this with F1: “Welcome to the demo.”

→ list_voices, then text_to_speech (saved as a WAV you can play).

Audit the account

How many agents do I have, what’s my credit balance, and what did I spend in the last week?

→ list_agents (paginated), get_credit_balance, and get_usage with a start date.

Get notified instead of polling

Register a webhook at https://example.com/hooks/bithuman for agent.ready and send it a test event.

→ create_webhook (returns the one-time signing secret), then test_webhook. See Webhooks for verifying the X-BitHuman-Signature header.

Configuration

The built-in server speaks the standard MCP stdio transport, so there’s nothing else to configure.

Notes

• Async work. generate_agent and generate_dynamics return immediately with processing. Have the agent poll get_agent_status / get_dynamics until ready (a few minutes for first-generation models; roughly 45 minutes to 1.5 hours for the second generation, which trains a real per-identity model).
• Credits. generate_agent (250 credits for the default first-generation model; 500 for essence-2, 2000 for expression-2 — see Pricing) and text_to_speech consume credits — check get_credit_balance first if cost matters.
• Errors come back as a structured object with the HTTP status and a link to the error catalog; the agent can read and act on them.