Developer Docs
MCP server
Connect Claude, Cursor, VS Code or any MCP client to the Toktik API with one config block, then ask your AI for TikTok LIVE rankings, gifters and agencies.
@toktikhq/mcp is a Model Context Protocol (MCP) server that runs on your computer next to your AI app. It reads rankings, creators, gifters, follow lists, the LIVE agency directory, creators to recruit and LIVE Pro creators with your own API key: you ask in plain words and the AI picks the right call.
| Package | Version | Needs |
|---|---|---|
@toktikhq/mcp | 0.1.1 | Node.js 24+ and a Toktik API key |
1. Create an API key
Open Developer and create a key. Give it the scopes of the tools you want; to use every tool, give it rank:read, gifter:read, creator:read, agencies:read, live-pro:read and trend:read. The Free plan works: no card needed.
2. Add the server to your app
Claude Desktop, in one click: download toktik-mcp.mcpb, open it (or drag it onto Settings → Extensions), click Install and paste your key. Claude Desktop runs it with its own Node.js and keeps the key in your system's keychain. For any other app, or to set Claude Desktop up by hand:
Paste your key in place of ttk_live_your_key. npx downloads the server the first time it runs; there is nothing else to install.
{
"mcpServers": {
"toktik": {
"command": "npx",
"args": [
"-y",
"@toktikhq/mcp"
],
"env": {
"TOKTIK_API_KEY": "ttk_live_your_key"
}
}
}
}Any other MCP client that runs a local command (Zed, Cline, Continue and others) uses the same command, npx -y @toktikhq/mcp, with TOKTIK_API_KEY set in its environment.
3. Ask
Restart the app, check that the toktik tools are listed, then ask things like:
- “Show today's daily LIVE ranking for Vietnam and tell me who moved up the most.”
- “Who are the top 10 gifters of @creator this week, and how much did each one give?”
- “Show the first page of accounts @creator follows.”
- “List the 10 largest LIVE agencies in MENA and the contact details they published.”
- “Which creators in Vietnam are live now and worth recruiting this month?”
- “Compare the follower counts and recent profile changes of @creator_a and @creator_b.”
Tools
Each tool is one read of the API, so it answers exactly what that endpoint answers, with the time and source of the data.
| Tool | Returns | Scope |
|---|---|---|
rankings_official | TikTok's official LIVE ranking board for a region: rank, score and creator. | rank:read |
rankings_movers | The biggest rank gainers and losers on a board since its previous period. | rank:read |
rankings_history | Past periods of a board, newest first. | rank:read |
rankings_regions | The regions with ranking boards, and which boards each one has. | rank:read |
gifters_list | Top gifters by what we saw them give in the last 24 hours, 7 or 30 days. | gifter:read |
gifters_get | One gifter's profile and the creators they gift to. | gifter:read |
gifters_for_creator | The gifters behind one creator, ranked by what they gave. | gifter:read |
creators_search | Find creators by name or handle, or browse by region, followers and LIVE now. | creator:read |
creators_get | A creator's profile: followers, bio, region and linked accounts. | creator:read |
creators_changes | A creator's recent name, handle and bio changes. | creator:read |
creators_analysis | A summary of a creator built from what we have observed. | creator:read |
creators_following | The accounts a creator follows, page by page. | creator:read |
creators_followers | A sample of a creator's most recent followers. | creator:read |
gifters_history | One gifter's coins over time by day, week, month or year, split by creator (Pro plan and above). | gifter:read |
gifters_live_for_creator | The gifters of a creator's current LIVE session (or the one that just ended), ranked by coins. | gifter:read |
agencies_list | TikTok's LIVE agency directory: filter by region, name, services; sort by size or newest. | agencies:read |
agencies_get | One agency in full, with the contact details it published on TikTok. | agencies:read |
agencies_regions | The agency directory's regions, each with its agency count. | agencies:read |
recruit_list | Creators worth recruiting: today's score, 30-day diamonds, followers, live now first. | rank:read |
recruit_creator_days | One creator's diamonds day by day over the last 30 days (Scale plan and above). | rank:read |
live_pro_list | LIVE Pro creators in a country, with who is live now. | live-pro:read |
trends_list | Trending hashtags or sounds for a region. | trend:read |
The realtime LIVE stream, videos and comments are not in the MCP server. Use the realtime stream or the SDKs for those.
Credits and plan limits
A tool spends credits exactly like the API call behind it, and your plan's limits apply the same way: hidden names on ranking boards, how far back history goes, requests per day. Most reads cost 1 credit, and a creator we have not stored yet costs 1,250 credits the first time. A follow list is collected from TikTok in steps of up to 150 accounts, 4,000 credits each: asking for a page past what is collected, or reading the list again after 12 hours, collects another step. The server tells the AI to fetch only the pages you ask for, so ask for "the first page" or a number of accounts rather than "everyone" on a big account. See Rate limits & Credits.
The first read of a new creator or follow list can answer "not ready yet" while we fetch it from TikTok. That answer is never billed, and the server tells the AI to ask again after a few seconds, so you usually just see the result arrive a little later.
If something goes wrong
| What you see | What to do |
|---|---|
TOKTIK_API_KEY is required | The app shows the server as failed or disconnected, and this line is in its MCP log. The env block is missing or the key is empty: add your key and restart the app. |
Unauthorized (check TOKTIK_API_KEY) | The key is wrong or was revoked. Create a new one in Developer and paste it again. |
Forbidden — your API key is missing the required scope | The key does not have the scope that tool needs (see the table). Create a key with that scope. |
Forbidden — your plan does not include this read | A few tools need a higher plan: a gifter's history needs Pro, a creator's 30 days needs Scale. Upgrade in Billing. |
Payment required | The workspace is out of credits, or the read needs a higher plan. Top up or upgrade in Billing. |
Rate limited | Too many calls in a short time. Wait a moment; the limit resets on its own. |
To check the server by hand, run it in a terminal; it prints one line when it is ready:
TOKTIK_API_KEY=ttk_live_your_key npx -y @toktikhq/mcp
# toktik-mcp v0.1.1 ready (22 tools) — base https://api.toktikhq.com