# tiktok-studio-mcp

MCP server for TikTok. Publishes videos to **your own** TikTok account and reads
back how they performed, through TikTok's official Content Posting and Display
APIs.

Built as the TikTok counterpart to
[`yt-studio-mcp`](https://github.com/aaronckj/yt-studio-mcp).

## What it can and cannot do

TikTok's creator APIs are narrower than YouTube's. Rather than advertise tools
that cannot work, this server exposes only what the platform actually supports:

| capability | supported |
|---|---|
| Upload video (drafts or direct post) | yes |
| View / like / comment / share counts | yes |
| List your videos | yes |
| **List or moderate comments** | **no** — TikTok offers this only through the Research API, which is gated to academic institutions |
| Playlists, captions, thumbnails | no — no API surface |

## Posting modes

TikTok gates direct publishing behind an app audit, so there are two modes,
selected with `TIKTOK_MCP_MODE`:

- **`upload`** (default) — the video lands in your TikTok inbox/drafts and you
  finish posting it in the app. Works without an audit.
- **`publish`** — posts directly. Requires the `video.publish` scope, which
  needs TikTok's full app audit (2–4 weeks, demo video, privacy policy, domain
  verification).

**Until the app is audited, TikTok forces everything an unaudited client posts
to private**, whatever `privacy_level` you ask for. `post_video` says so in its
result rather than letting you assume something published.

## Install

```bash
claude mcp add tiktok -s user -- uvx tiktok-studio-mcp
```

## Authenticate

Register an app at [developers.tiktok.com](https://developers.tiktok.com) with
Login Kit, Content Posting API and Display API, requesting the scopes
`user.info.basic`, `video.upload`, `video.list`, `video.publish`. Set the
Desktop redirect URI to `http://localhost:8902/`.

```bash
export TIKTOK_MCP_CLIENT_KEY=...
export TIKTOK_MCP_CLIENT_SECRET=...
tiktok-studio-mcp auth
```

Prefer the environment over `--client-key` / `--client-secret`: command-line
arguments are visible to any user on the box via `ps` and land in shell history.
The flags still work as a fallback.

The flow is **headless-friendly**: it binds a fixed port and prints the consent
URL rather than launching a browser. On a machine with a browser:

```bash
ssh -N -L 8902:localhost:8902 user@your-host
```

then open the printed URL.

## Tools

| tool | purpose |
|---|---|
| `health_check` | credentials refresh, account reachable, granted scopes, active mode |
| `creator_info` | nickname, allowed privacy levels, duration cap, interaction toggles |
| `post_video` | upload a file; returns `publish_id`. Supports `dry_run` |
| `post_status` | poll a `publish_id` |
| `list_videos` | your videos, with statistics |
| `video_stats` | counts for specific video ids |

`post_video` calls `creator_info` first and validates `privacy_level` against
what the account actually allows, because TikTok rejects mismatches with an
unhelpful error.

## Secrets

`TIKTOK_MCP_SECRETS` selects the backend: `file` (default,
`~/.config/tiktok-studio-mcp/credentials.json`, mode 600), `env`, or `vaultproxy`.

**TikTok rotates refresh tokens** — every refresh returns a new one and
invalidates the old. This server writes the new token back on every refresh; if
it did not, authentication would work for 24 hours and then fail with no obvious
cause.

## Limits

Enforced by TikTok, surfaced by this server:

- **6 requests per minute** per access token on the init endpoints
- **5 pending shares per 24 hours**
- chunked upload: files under 5 MB go whole; otherwise chunks are 5–64 MB, the
  final chunk may reach 128 MB, 1–1000 chunks, 4 GB maximum

## Development

```bash
pip install -e '.[dev]'
ruff check src tests
pytest
```

Tests use an injected transport and need no TikTok credentials.

## License

MIT