Docs index: /llms.txt · every page as Markdown: add .md

Docs
Console Discord Get API secret
‹ Guides

Claude & Cursor (MCP)

Let Claude, Cursor and other MCP clients drive bitHuman as tools.

CLI 2.8.9

View as Markdown Open in ChatGPT Open in Claude

bithuman mcp is a Model Context Protocol server built into the CLI. An MCP client such as Claude Code, Claude Desktop or Cursor can then call bitHuman as tools: “make an avatar that explains our pricing, then give me an embed token” becomes a chain of tool calls.

What you’ll build

Your MCP client can create avatars, render talking videos, embed agents and check your credits by calling bitHuman tools.

You need:

  • The CLI on macOS (Apple silicon), Linux or Windows. In a hosted agent, call the REST API directly.
  • An MCP client.

Steps

3 steps

  1. Install

    The server is the CLI; there is nothing else to install.

    curl -fsSL https://install.bithuman.ai | sh
bithuman mcp tools      # prints the tool list and exits
    Expected

    bithuman mcp tools prints the tool list and exits.

  2. Authenticate

    Run bithuman login once, or set BITHUMAN_API_SECRET in the client’s configuration. The server reads the same credential as the CLI and never logs it.

    Expected

    After bithuman login, bithuman account shows your plan and credit balance.

  3. Connect your client

    Register the server with your client.

    Claude Code:

    claude mcp add bithuman -- bithuman mcp

    Claude Desktop, Cursor (~/.cursor/mcp.json) and other clients:

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

    If you have not run bithuman login, add "env": {"BITHUMAN_API_SECRET": "<your API secret>"} to that entry.

    Then ask: “Use the bithuman tools to validate my API secret.” The client calls validate_api_secret and reports {"valid": true}.

    Expected

    The client reports {"valid": true} from validate_api_secret.

How it works

  • Agent creation is asynchronous: a second-generation agent takes about 2–2.5 hours. Prices are on pricing.
  • Errors come back as structured objects with the HTTP status and a link to Errors.

Make it your own

Ask in plain language; the client chooses and chains the tools.

AskTools it calls
”Create an Expression 2 avatar from this image, wait until it is ready, and give me an embed token.”generate_agent, get_agent_status, create_embed_token
”What is my credit balance, and what did I spend this week?”get_credit_balance, get_usage
”Register a webhook at https://example.com/hooks and send it a test event.”create_webhook, test_webhook
”Download wise-pup and render this WAV to an MP4.”pull, render

Tools

ToolWhat it does
version, doctorCLI version and install health (local)
inspect_model, list_showcase, pull, renderInspect, list, download and render avatars on this machine (local)
validate_api_secretCheck the API secret (free)
get_platform_statusService status from status.bithuman.ai
get_credit_balance, get_usageBalance, plan and usage history
generate_agent, get_agent_statusCreate an agent from an image (spends credits; always pass model), then poll until ready or failed
get_agent, list_agents, update_agent_prompt, delete_agentManage your agents
agent_speak, add_agent_contextMake a live agent speak, or give it background knowledge
get_dynamics, generate_dynamicsList or create gestures (spends credits)
create_embed_tokenA one-hour token to embed an agent on a website
upload_fileUpload an asset and get a URL
create_webhook, list_webhooks, delete_webhook, test_webhookWebhooks

There is no text-to-speech tool: bitHuman does not synthesize speech. Make a WAV with any TTS and pass it to render, or send it to the talking-video API. CLI 2.8.7 and earlier still list list_voices and text_to_speech; both now return 410 ENDPOINT_RETIRED.

The cloud talking-video API, adding a model to an agent and knowledge bases have no tool; use the REST API.

Troubleshooting

SymptomCauseFix
No bithuman tools in the clientbithuman is not on the client’s PATHuse the full path to the binary in the config, then restart the client
validate_api_secret returns valid: falseno or wrong credentialbithuman login, or set BITHUMAN_API_SECRET in the config
A created agent uses a first-generation modelmodel was not passedask for essence-2 or expression-2 explicitly
422 MODEL_SUBJECT_MISMATCH when creating an agentthe subject is not a real person, or no face was found; every model but Expression 2 needs onechoose Expression 2 (Choosing a model)

Next

This section moved: docs.bithuman.ai/build/mcp#connect-your-client

This section moved: docs.bithuman.ai/build/mcp#what-youll-build

This section moved: docs.bithuman.ai/build/mcp#make-it-your-own

This section moved: docs.bithuman.ai/build/mcp#how-it-works

This section moved: docs.bithuman.ai/build/mcp#next