tiktok-mcp

# TikTok MCP Server

<!-- mcp-name: com.hasdata/tiktok -->

A hosted Model Context Protocol (MCP) server that gives Claude, Cursor, Windsurf and any other MCP client four read-only TikTok tools. Look up a public profile, walk an account's videos, read the comments on a video, and search TikTok for videos or creators, all as structured JSON, with no TikTok developer account and no OAuth.

It reads public data that a signed-out visitor can see. It does not sign in, post, or act as an account.

```
https://mcp.hasdata.com/api/mcp?apis=tiktok
```

[![Glama score](https://glama.ai/mcp/servers/HasData/tiktok-mcp/badges/score.svg)](https://glama.ai/mcp/servers/HasData/tiktok-mcp)
[![tool contract](https://github.com/HasData/tiktok-mcp/actions/workflows/contract.yml/badge.svg)](https://github.com/HasData/tiktok-mcp/actions/workflows/contract.yml)
[![MCP](https://img.shields.io/badge/MCP-remote%20%7C%20streamable%20HTTP-6366f1?style=flat-square)](https://modelcontextprotocol.io)
[![Tools](https://img.shields.io/badge/tools-4-10b981?style=flat-square)](#tools)
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)

## Contents

- [What you need](#what-you-need)
- [Quick start](#quick-start)
- [Example prompts](#example-prompts)
- [Tools](#tools)
- [Errors and failure paths](#errors-and-failure-paths)
- [Pricing, free tier and limits](#pricing-free-tier-and-limits)
- [Tool selection](#tool-selection)
- [How it compares](#how-it-compares)
- [FAQ](#faq)
- [HasData links](#hasdata-links)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)

## What you need

An MCP client and a HasData API key from the [dashboard](https://app.hasdata.com/sign-up?utm_source=github&utm_medium=syndication&utm_campaign=tiktok-mcp), free to create. This is a remote server, so the simplest path is a URL and an `x-api-key` header, with no container to run and no TikTok developer account anywhere in the flow. A client that only speaks stdio reaches it through a thin launcher, published as `@hasdata/tiktok-mcp` on npm and `hasdata-tiktok-mcp` on PyPI, shown below.

## Quick start

The server URL is the same for every client. We run it hands-on in Claude Code and Claude Desktop. The other blocks follow each client's own documented format for a remote server.

| Field | Value |
| :--- | :--- |
| URL | `https://mcp.hasdata.com/api/mcp?apis=tiktok` |
| Transport | HTTP, streamable |
| Auth header | `x-api-key: HASDATA_API_KEY` |

Clients with OAuth support can add the same URL as a connector and sign in without putting a key in a config file.

<details>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add --transport http tiktok "https://mcp.hasdata.com/api/mcp?apis=tiktok" \
  --header "x-api-key: HASDATA_API_KEY"
```

</details>

<details>
<summary><b>Claude Desktop</b></summary>

Settings, then Connectors, then Add custom connector, then paste `https://mcp.hasdata.com/api/mcp?apis=tiktok` and sign in.

For the config-file route, Claude Desktop loads only local (stdio) servers, so it reaches a remote server through a stdio launcher. The `@hasdata/tiktok-mcp` package is that launcher, and it reads the key from the environment. Add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tiktok": {
      "command": "npx",
      "args": ["-y", "@hasdata/tiktok-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}
```

Python instead of Node? Swap the launcher for the PyPI package, which `uvx` runs without a manual install:

```json
{
  "mcpServers": {
    "tiktok": {
      "command": "uvx",
      "args": ["hasdata-tiktok-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Cursor</b></summary>

`~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one:

```json
{
  "mcpServers": {
    "tiktok": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=tiktok",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Windsurf</b></summary>

`~/.codeium/windsurf/mcp_config.json`. Windsurf calls the field `serverUrl`, not `url`:

```json
{
  "mcpServers": {
    "tiktok": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=tiktok",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Cline</b></summary>

```json
{
  "mcpServers": {
    "tiktok": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=tiktok",
      "type": "streamableHttp",
      "headers": { "x-api-key": "HASDATA_API_KEY" },
      "disabled": false
    }
  }
}
```

</details>

<details>
<summary><b>VS Code</b></summary>

`.vscode/mcp.json` in the workspace:

```json
{
  "servers": {
    "tiktok": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=tiktok",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Codex CLI</b></summary>

`~/.codex/config.toml`:

```toml
[mcp_servers.tiktok]
url = "https://mcp.hasdata.com/api/mcp?apis=tiktok"

[mcp_servers.tiktok.headers]
"x-api-key" = "HASDATA_API_KEY"
```

</details>

<details>
<summary><b>Gemini CLI</b></summary>

`~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "tiktok": {
      "httpUrl": "https://mcp.hasdata.com/api/mcp?apis=tiktok",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

## Example prompts

Prompts, not code. Paste one in and the agent picks the tool itself. Each is annotated with the calls it takes, because in MCP the model decides how many calls to make and every successful call costs 10 credits.

> Take @mrbeast. Pull the profile, then walk the first two pages of videos and give me the median play count across them.

*Three calls, 30 credits. The profile is one call, and each page of videos is another.*

> Search TikTok for creators around "cold brew coffee" and rank the top ten by followers, each with their bio.

*One call, 10 credits. A user search already carries follower count and bio, so no per-profile follow-up is needed.*

> Here is a video URL. Read its top comments and tell me the overall sentiment and the three most-liked replies.

*One call, 10 credits. The numeric id in the URL is all the comments tool needs.*

> Take that same video, then expand the replies under its most-liked comment.

*Two calls, 20 credits. Top-level comments first, then a second call with that comment's id for its replies.*

> Search "asmr" videos, then pull the author profile of the three with the highest play counts.

*Four calls, 40 credits. One search, then one profile each. Every author in a search result carries a link straight to its profile endpoint, so the agent never has to guess a handle.*

Paging costs a call each time. A creator audit that reads a profile then walks five pages of videos is six calls and 60 credits. The trial goes further on narrow questions than on open-ended crawls.

## Tools

Four tools, all read-only. Samples below are trimmed from real calls, and the numbers in them move as TikTok updates. Read them as shapes. Each tool name links to its endpoint reference, which carries the full field list.

The samples are the payload, not the whole response. A `tools/call` result carries one text block, and that text is itself JSON holding `url`, `status`, `text` and `json`, with the scraped data under `json`. From a raw JSON-RPC response the path is `result.content[0].text`, parsed, then `.json`. A chat client unwraps that for you and code talking to the endpoint directly does not.

Handles, video ids and comment ids chain together. A profile links to its posts, every post carries its own video id for the comments tool, and every author in comments and search results carries a `hasdataLink` to its profile and a `hasdataPostsLink` to its videos. An agent walks from a keyword to a creator to a video to its comments without ever constructing a URL.

### Get TikTok profile

[`hasdata_tiktok_profile_getTikTokProfile`](https://docs.hasdata.com/apis/tiktok/profile?utm_source=github&utm_medium=syndication&utm_campaign=tiktok-mcp)

One public account by handle.

| Parameter | Type | Required | Notes |
| :--- | :--- | :--- | :--- |
| `handle` | string | yes | The username, with or without the leading `@` |

Returns `username`, `nickname`, `biography`, `bioLink`, `verified`, `language`, `createTime`, the avatar URLs, and the `followers`, `follows`, `likes`, `videos` and `friends` counts as integers. The counts are already parsed, so `followers > 1000000` compares numbers, not display strings.

> A handle that does not exist still comes back with `requestMetadata.status` set to `ok`, the `profile` object simply absent. Check that the object is there before reading `username` or any other field, or an agent doing `profile.username` throws on nothing.

```json
{
  "username": "mrbeast",
  "nickname": "MrBeast",
  "verified": true,
  "biography": "Checkout My New Book!👇",
  "bioLink": "http://themostdangerousgames.com",
  "createTime": "2018-10-20T19:26:16.000Z",
  "followers": 138387571,
  "follows": 354,
  "likes": 1427086888,
  "videos": 466,
  "friends": 285
}
```

### Get TikTok posts

[`hasdata_tiktok_posts_getTikTokPosts`](https://docs.hasdata.com/apis/tiktok/posts?utm_source=github&utm_medium=syndication&utm_campaign=tiktok-mcp)

A page of an account's videos by handle, newest first.

| Parameter | Type | Required | Notes |
| :--- | :--- | :--- | :--- |
| `handle` | string | yes | The username, with or without the leading `@` |
| `nextPageToken` | string | | The `pagination.nextPageToken` from the previous response. Omit it for the first page |

One call returns about thirty videos plus `pagination`, which carries `hasMore` and the `nextPageToken` you feed back to walk the account history one page at a time. Each video carries `id`, `description`, `url`, `duration`, the cover and playable video URLs, `music`, and the `likes`, `comments`, `shares`, `plays`, `co