Skip to main content
Glama
tiktok-live-mcp

tiktok-live-mcp

by tiktooldev
README.md
# TikTok LIVE MCP

An MCP (Model Context Protocol) server that gives Claude, Cursor, VSCode and any MCP client live access to TikTok LIVE data: detect who is live, pull room and creator data, gift catalogs and regional leaderboards across 44 regions, straight from a chat prompt.

Powered by the [tik.tools](https://tik.tools) platform. Sandbox is a 7-day evaluation, no credit card; after 7 days requests return "Evaluation period ended" until you pick a plan. Full unmasked leaderboards, league and gaming boards, the eligible-creator recruiting feed, and the real-time event WebSocket are available at [tik.tools/pricing](https://tik.tools/pricing).

## Quick install

Get an API key at [tik.tools/pricing](https://tik.tools/pricing), then add the server to your client.

### Claude Desktop

Edit `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tiktok-live": {
      "command": "npx",
      "args": ["-y", "tiktok-live-mcp"],
      "env": { "TIKTOOLS_API_KEY": "YOUR_KEY" }
    }
  }
}
```

### Cursor

Add to `~/.cursor/mcp.json` (or the project `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "tiktok-live": {
      "command": "npx",
      "args": ["-y", "tiktok-live-mcp"],
      "env": { "TIKTOOLS_API_KEY": "YOUR_KEY" }
    }
  }
}
```

### VSCode

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "tiktok-live": {
      "command": "npx",
      "args": ["-y", "tiktok-live-mcp"],
      "env": { "TIKTOOLS_API_KEY": "YOUR_KEY" }
    }
  }
}
```

## Configuration

| Env var | Default | Notes |
|---|---|---|
| `TIKTOOLS_API_KEY` | - | API key. Get one at https://tik.tools/pricing |
| `TIKTOOL_API_KEY` | - | Accepted alias for `TIKTOOLS_API_KEY` |
| `TIKTOK_LIVE_API_KEY` | - | Accepted alias for `TIKTOOLS_API_KEY` |
| `TIKTOOLS_API_BASE` | `https://api.tik.tools` | Override only for testing. Non tik.tools hosts are refused so the key cannot be redirected |
| `TIKTOOL_API_BASE` | - | Accepted alias for `TIKTOOLS_API_BASE` |

Set any one of the three key variables. They are read in the order listed above.

## Tools

Eleven tools. Tier requirements are stated on every tool that is gated; when your key is below the required tier the tool returns a clear upgrade message instead of failing.

| Tool | What it does | Minimum tier |
|---|---|---|
| `get_live_status` | Is a single creator live now, plus room id | Any |
| `check_live` | Live check for a batch of creators in one call | Basic |
| `get_room_info` | Title, viewers, uptime and host for a live room | Basic |
| `get_creator_profile` | Full creator profile by username | Pro |
| `get_gift_catalog` | Gift id, name, diamond cost and icon | Any (full catalog from Pro) |
| `get_gift_gallery` | A creator's live gift wishlist and progress | Any |
| `get_live_feed` | Discover streams live right now in a region | Pro |
| `get_leaderboard` | Regional creator leaderboard by diamonds | Any for daily (masked below Pro), Ultra for league, Agency for weekly, gaming, shopping |
| `get_popular_live` | TikTok's Popular LIVE board per region | Any (unmasked at Global Agency) |
| `find_eligible_creators` | Score-ranked creators to recruit in a region | Global Agency |
| `get_rate_limits` | Your key's tier, quota and WebSocket allowance | Any |

### Worked examples

Ask your MCP client in plain language; it selects the tool and arguments. The arguments each tool receives are shown below.

**`get_live_status`** - "Is creator_username live right now?"

```json
{ "username": "creator_username" }
```

```json
{ "username": "creator_username", "unique_id": "creator_username", "is_live": true, "room_id": "7000000000000000001", "cached": true }
```

**`check_live`** - "Which of these creators are live: creator_username, another_creator?"

```json
{ "usernames": ["creator_username", "another_creator"] }
```

```json
{
  "checked": 2,
  "live_now": ["creator_username"],
  "results": [
    { "username": "creator_username", "is_live": true, "room_id": "7000000000000000001", "viewers": null },
    { "username": "another_creator", "is_live": false, "room_id": "7000000000000000002", "viewers": null }
  ]
}
```

**`get_room_info`** - "What is creator_username streaming and how many viewers?"

```json
{ "username": "creator_username" }
```

```json
{
  "username": "creator_username",
  "is_live": true,
  "room_id": "7000000000000000001",
  "title": "Lets Go LIVE!",
  "viewers": 47,
  "started_at": "2026-08-02T08:42:28.000Z",
  "live_duration_seconds": 14041,
  "owner": { "id_str": "1234567890123456789", "nickname": "Creator Name", "display_id": "creator_username" }
}
```

**`get_creator_profile`** - "Show me the TikTok profile for creator_username." (Pro)

```json
{ "username": "creator_username" }
```

Returns nickname, bio, verification flag, avatar, follower and video counts.

**`get_gift_catalog`** - "What TikTok gifts cost the most diamonds?" Callable with no arguments.

```json
{}
```

```json
{
  "scope": "global catalog",
  "total_matching": 646,
  "returned": 100,
  "gifts": [{ "id": 5655, "name": "Rose", "diamond_count": 1, "icon": "https://..." }]
}
```

Filter and scope it: `{ "search": "rose", "limit": 3 }` returns only matching gifts. Passing `{ "username": "creator_username" }` scopes the catalog to that creator's live room.

**`get_gift_gallery`** - "What gift goals has creator_username set for this stream?"

```json
{ "username": "creator_username" }
```

Returns the wishlist with per-gift progress. If the creator is offline the tool answers with `is_live: false` and an explanatory note rather than an error.

**`get_live_feed`** - "Show me 3 TikTok streams live in the US right now." (Pro)

```json
{ "region": "US", "count": 3 }
```

```json
{
  "region": "US",
  "returned": 3,
  "daily_feed_remaining": 91,
  "streams": [
    { "username": "third_creator", "nickname": "Third Creator", "title": "Live now", "viewers": 1, "room_id": "7000000000000000003", "followers": 812 }
  ]
}
```

**`get_leaderboard`** - "Who are the top TikTok LIVE creators in Korea today?"

```json
{ "region": "KR", "type": "daily" }
```

```json
{ "type": "daily", "region": "KR", "region_label": "South Korea", "tier": "pro", "count": 99,
  "entries": [{ "rank": 1, "unique_id": "top_creator", "nickname": "Top Creator", "score": 1667836, "is_live": false }] }
```

`type` accepts `daily`, `weekly`, `league`, `gaming` and `shopping`. Requesting a board above your tier returns the requirement:

```json
{ "gated": true, "httpStatus": 403, "message": "The league leaderboard is a Ultra-tier feature.", "required_tier": "ultra", "current_tier": "pro", "upgrade": "https://tik.tools/pricing" }
```

**`get_popular_live`** - "What is TikTok featuring on the Popular LIVE board in Korea?"

```json
{ "region": "KR" }
```

Returns the ranked board. Below Global Agency the creator identifiers come back masked, with `_upgrade_required` on each masked row.

**`find_eligible_creators`** - "Find creators worth recruiting in the US." (Global Agency)

```json
{ "region": "US", "min_score": 1000, "limit": 10 }
```

**`get_rate_limits`** - "How much API quota do I have left?"

```json
{}
```

```json
{ "status_code": 0, "data": { "tier": "pro", "api": { "limit": 120, "remaining": 112 }, "websocket": { "limit": 50, "current": 0 },
  "daily": { "limit": 75000, "used": 8, "remaining": 74992 }, "bulk_check_limit": 50 } }
```

`api.limit` is requests per minute, `daily.limit` requests per day, `websocket.limit` concurrent streams.

## Plan limits

| Plan | Requests/day | Requests/min | Concurrent streams | WebSocket sessions/day | Max session length |
|---|---|---|---|---|---|
| Sandbox (7-day evaluation) | 5,000 | 20 | 3 | 50 | 2 h |
| Basic | 10,000 | 30 | 20 | 300 | 8 h |
| Pro | 75,000 | 120 | 50 | 3,000 | 12 h |
| Agency Starter | 75,000 | 120 | 100 | 3,000 | 12 h |
| Ultra | 300,000 | 300 | 250 | Unlimited | 24 h |
| Agency Global | 1,000,000 | 1,000 | 500 | Unlimited | 24 h |

Current prices: [tik.tools/pricing](https://tik.tools/pricing). Live service status: [tik.tools/status](https://tik.tools/status).

## Real-time events

The REST tools above answer point-in-time questions. For live chat, gift, like and battle streams (90+ event types), connect a WebSocket:

```
wss://api.tik.tools/?uniqueId=<username>&apiKey=YOUR_KEY
```

Full docs: [tik.tools/docs](https://tik.tools/docs)

## Changes in 0.2.4

- Registry metadata: `mcpName` for the official MCP Registry, `glama.json`, a `Dockerfile` for container hosts, and an MCPB `manifest.json` for one-click local installs.
- Sandbox wording: a 7-day evaluation, no credit card.

## Changes in 0.2.0

- `get_gift_catalog` now works when called with no arguments and returns the parsed catalog, with optional `search` and `limit`.
- `get_live_status`, `get_room_info` and `check_live` now return a real live answer. Previously they returned an instruction to go fetch tiktok.com, which an MCP client cannot do.
- `get_live_feed` now returns parsed stream listings instead of a signed URL, and honours `count`.
- Added `get_leaderboard` with a `type` parameter so daily, weekly, league, gaming and shopping boards are reachable.
- `TIKTOOL_API_KEY` and `TIKTOK_LIVE_API_KEY` are accepted alongside `TIKTOOLS_API_KEY`.
- Every gated tool now states its minimum tier in its description.
- Removed `get_creator_earnings`, `get_room_rankings` and `get_trending_hashtags`. The first two need an authenticated TikTok session that an MCP client cannot supply, and the third had no working data source. They are gone rather than shipped broken.

## License

MIT