chaturbate-mcp

Read-only MCP server exposing three Chaturbate APIs as tools, for use from Claude Code or any MCP client (e.g. lobehub):

Built with the official Python MCP SDK (mcp ≥ 2.1, the release that renamed FastMCP → MCPServer) and httpx2.

Requirements

• Python ≥ 3.10 (developed on 3.14)
• uv

Install

uv sync --dev

Configure

Copy .env.example to .env and fill in your Chaturbate account values:

cp .env.example .env   # then edit

Credentials are read from the environment, with .env as a local convenience:

• CHATURBATE_USERNAME — your Chaturbate account
• CHATURBATE_STATS_TOKEN — Stats-API scope token. The same token authorizes both the room-stats and the affiliate-earnings endpoints.
• CHATURBATE_EVENTS_TOKEN — Events-API scope token for the live feed. A private scope exposes tips + private messages; a public scope omits them.

Create/manage tokens at https://chaturbate.com/statsapi/authtoken/.

.env is gitignored. Never commit a real token.

Run

Start the stdio server manually:

uv run chaturbate-mcp

For Claude Code, a project-scoped entry is committed in .mcp.json (launches via uv, no secrets in the config — the server reads them from .env). Approve the chaturbate server once under /mcp.

Tools

Streaming events

The events feed is cursor-based and stateless:

1. fetch_events(timeout=0) → returns {events, next_url} (recent events + a cursor).
2. Pass that next_url back to fetch_events(next_url=…) to receive the next batch.
3. events: [] + a valid next_url means nothing new in the window — poll again.

timeout (0–90 s) is how long the server waits for new events before returning. Default to 0 for a quick peek; a long poll can exceed an MCP client's tool-call deadline.

The companion skill .claude/skills/chaturbate/ documents these workflows for Claude Code.

Tests

Offline unit tests (no network, no tokens):

uv run pytest -q

Live smoke test against the real API — it reads the account/tokens from review/Stats Token Authorization - Chaturbate.html in memory (or CHATURBATE_* env) and never prints or persists them:

uv run python scripts/smoke_test.py

Releasing (PyPI)

This package publishes to PyPI from GitHub Actions via a Trusted Publisher (OIDC) — no API tokens or passwords are used.

To cut a release:

1. Bump version in pyproject.toml, commit, and push.
2. Tag and push the tag (must match the new version): git tag v0.1.0 && git push origin v0.1.0
3. .github/workflows/publish-python.yml runs the offline tests, builds the wheel + sdist, smoke-tests the install, then publishes to https://pypi.org/project/chaturbate-mcp.

The PyPI trusted publisher is registered once at https://pypi.org/manage/account/publishing/ with exactly these values (the workflow name and environment must match the file/job in this repo):

Security notes

• review/ (a saved copy of your authtoken page — contains live tokens) and mitm_mcp_traffic.db are gitignored and must never be committed. See CLAUDE.md.
• Real tokens live only in .env (gitignored) or the environment.
• Events next_url values embed the events token. Treat tool output as sensitive: do not echo feed URLs verbatim into chat, logs, or files.
• API error messages are redacted before they reach the client.

Caveats

• Stats are ~5 minutes stale upstream; don't treat a single snapshot as live.
• Affiliate date-range params are undocumented and unreliable — Chaturbate can answer rapid requests carrying them with HTTP 403 (throttling). The tool sends none by default.
• The affiliate/room-stats data refreshes once every ~5 minutes regardless of request rate.
• The events feed rate limit is 2000 requests/minute.