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.

PackageVersionNeeds
@toktikhq/mcp0.1.1Node.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"
      }
    }
  }
}
Settings → Developer → Edit Config opens claude_desktop_config.json. Paste the block, save, then quit and reopen Claude.

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.

ToolReturnsScope
rankings_officialTikTok's official LIVE ranking board for a region: rank, score and creator.rank:read
rankings_moversThe biggest rank gainers and losers on a board since its previous period.rank:read
rankings_historyPast periods of a board, newest first.rank:read
rankings_regionsThe regions with ranking boards, and which boards each one has.rank:read
gifters_listTop gifters by what we saw them give in the last 24 hours, 7 or 30 days.gifter:read
gifters_getOne gifter's profile and the creators they gift to.gifter:read
gifters_for_creatorThe gifters behind one creator, ranked by what they gave.gifter:read
creators_searchFind creators by name or handle, or browse by region, followers and LIVE now.creator:read
creators_getA creator's profile: followers, bio, region and linked accounts.creator:read
creators_changesA creator's recent name, handle and bio changes.creator:read
creators_analysisA summary of a creator built from what we have observed.creator:read
creators_followingThe accounts a creator follows, page by page.creator:read
creators_followersA sample of a creator's most recent followers.creator:read
gifters_historyOne gifter's coins over time by day, week, month or year, split by creator (Pro plan and above).gifter:read
gifters_live_for_creatorThe gifters of a creator's current LIVE session (or the one that just ended), ranked by coins.gifter:read
agencies_listTikTok's LIVE agency directory: filter by region, name, services; sort by size or newest.agencies:read
agencies_getOne agency in full, with the contact details it published on TikTok.agencies:read
agencies_regionsThe agency directory's regions, each with its agency count.agencies:read
recruit_listCreators worth recruiting: today's score, 30-day diamonds, followers, live now first.rank:read
recruit_creator_daysOne creator's diamonds day by day over the last 30 days (Scale plan and above).rank:read
live_pro_listLIVE Pro creators in a country, with who is live now.live-pro:read
trends_listTrending 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 seeWhat to do
TOKTIK_API_KEY is requiredThe 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 scopeThe 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 readA few tools need a higher plan: a gifter's history needs Pro, a creator's 30 days needs Scale. Upgrade in Billing.
Payment requiredThe workspace is out of credits, or the read needs a higher plan. Top up or upgrade in Billing.
Rate limitedToo 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:

Terminal
TOKTIK_API_KEY=ttk_live_your_key npx -y @toktikhq/mcp
# toktik-mcp v0.1.1 ready (22 tools) — base https://api.toktikhq.com