bitHuman MCP server

[!IMPORTANT] Deprecated — use the bitHuman CLI instead. This server is now built into the bithuman CLI: run bithuman mcp. It exposes the same tools (identical names) plus local ones (version, doctor, inspect_model, list_showcase), so you install one tool. Migrate your MCP client config:

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

Install the CLI: brew install bithuman-product/bithuman/bithuman-cli (macOS) or the universal installer (macOS + Linux) — see the CLI README. This bithuman-mcp package will receive no further updates.

A Model Context Protocol server that exposes the bitHuman avatar platform as tools any MCP-capable AI agent can call — Claude Desktop, Claude Code, Cursor, and others.

It's a thin, fully-documented wrapper over the public REST API (https://api.bithuman.ai). Every tool maps to one documented endpoint; see the API docs and the OpenAPI spec.

Tools

The server exposes 22 tools, each mapping to one documented REST endpoint (plus get_platform_status, which reads the public status feed):

Setup

You need an API secret from the Developer Dashboard.

Published on PyPI as bithuman-mcp. The easiest way to run it is with uvx (recommended for MCP clients), or pip install bithuman-mcp.

BITHUMAN_API_SECRET=bh-... uvx bithuman-mcp

Use with Claude Desktop / Claude Code

Add it to your MCP client config. For Claude Code:

claude mcp add bithuman \
  -e BITHUMAN_API_SECRET=bh-your-secret \
  -- uvx bithuman-mcp

For Claude Desktop (claude_desktop_config.json) or any client that takes a JSON server block:

{
  "mcpServers": {
    "bithuman": {
      "command": "uvx",
      "args": ["bithuman-mcp"],
      "env": { "BITHUMAN_API_SECRET": "bh-your-secret" }
    }
  }
}

Configuration

Notes

• Async work: generate_agent and generate_dynamics return immediately with a processing status. Poll get_agent_status / get_dynamics until ready (generation takes 2–5 minutes).
• Credits: generate_agent (~250 credits) and text_to_speech consume credits. Check get_credit_balance first if cost matters.
• Errors: non-2xx responses come back as a structured {error, status_code, body, hint} object. The error catalog is at https://docs.bithuman.ai/api/errors.

License

Apache-2.0.