Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@TikTok MCP Server search TikTok for #booktok and show me the top 5 videos"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server that lets an AI agent read public TikTok data: search, profiles, videos, discovery, comments, and transcription.
There is no TikTok developer account to apply for and no OAuth flow. Everything comes off public pages, so the only credential you might enter is a key for your own transcription endpoint.
It runs on any MCP client (Claude, Cursor, opencode, Codex) and returns structured output (structuredContent + outputSchema) from every tool. Transcription works against any OpenAI-compatible speech-to-text endpoint: Groq, OpenAI, or a Whisper server you host yourself.
Paste this into your MCP client config. There is nothing to install first: uvx fetches the package and runs it on the initial launch.
{
"mcpServers": {
"tiktok": {
"type": "stdio",
"command": "uvx",
"args": ["tiktok-mcp-server"],
"env": {
"TRANSCRIBE_API_URL": "https://api.groq.com/openai/v1",
"TRANSCRIBE_API_KEY": "your-key"
}
}
}
}Things worth knowing before the first call:
The env block exists only for transcribe_video. Write "env": {} if you want the other five tools and nothing else. The endpoint must serve an OpenAI-compatible POST /audio/transcriptions route backed by a speech-to-text model such as whisper-large-v3.
The first tool call downloads Playwright Chromium once, about 150 MB. ffmpeg ships with the package (imageio-ffmpeg); set FFMPEG_PATH if you'd rather use your own binary.
You need uv on the machine, since it provides uvx. Python 3.11+ comes along with it; uv installs that itself.
Linux only: headless Chromium needs system libraries that uvx can't install for you. On a fresh machine or Docker image, run this once (it may prompt for sudo):
uvx --from playwright playwright install-deps chromiumWindows and macOS don't need this step.
Not on PyPI yet? Point uvx at a local checkout or at the git repo (use whichever fits):
"args": ["--from", "C:\\path\\to\\tiktokmcp", "tiktok-mcp-server"]"args": ["--from", "git+https://github.com/<you>/tiktokmcp", "tiktok-mcp-server"]Related MCP server: TikTapDown MCP
Tool | Description | Parameters |
| Profile info: bio, follower/following/like/video counts, verified status, avatar |
|
| A user's recent videos with id, caption, URL, view count |
|
| Top-level comments: author, text, likes |
|
| Search by keyword or hashtag ( |
|
| Creators posting about a topic/hashtag |
|
| Download, extract audio, and transcribe via your speech-to-text API (reports progress) |
|
What the tools have in common:
count is validated to 1–50 by the input schema; username accepts handles with or without @
Video tools accept a full URL (including vm.tiktok.com / vt.tiktok.com short links), @user/video/<id>, or a bare numeric id
Every tool is annotated readOnlyHint, idempotentHint, openWorldHint, destructiveHint: false
Anticipated failures (bad input, user not found, missing TRANSCRIBE_API_URL, TikTok timeouts) come back as isError: true with a readable message
When TikTok blocks or hides data, tools return an empty list plus a note instead of failing
Each browser call takes several seconds; transcribe_video can take up to a minute. Counts like views/likes are TikTok's display strings (e.g. 1.2M)
Your MCP client injects configuration as environment variables. The server never reads a .env file of its own.
Variable | Required | Description |
| For transcription | OpenAI-compatible base URL ( |
| For transcription | API key for that endpoint (omit for keyless local servers) |
| No | Model name (default |
| No | Path to an ffmpeg binary (default: |
| No |
|
| No |
|
Built-in safety limits: 100 MB download cap, 120 s ffmpeg timeout, 600 s transcription timeout, 30 s navigation timeout.
Every client launches the same command, uvx tiktok-mcp-server. Only the config format differs.
{
"mcpServers": {
"tiktok": {
"type": "stdio",
"command": "uvx",
"args": ["tiktok-mcp-server"],
"env": {
"TRANSCRIBE_API_URL": "https://api.groq.com/openai/v1",
"TRANSCRIBE_API_KEY": "your-key"
}
}
}
}Claude Code one-liner:
claude mcp add tiktok -e TRANSCRIBE_API_URL=... -e TRANSCRIBE_API_KEY=... -- uvx tiktok-mcp-server~/.config/opencode/opencode.json → mcp)"tiktok": {
"type": "local",
"command": ["uvx", "tiktok-mcp-server"],
"environment": {
"TRANSCRIBE_API_URL": "https://api.groq.com/openai/v1",
"TRANSCRIBE_API_KEY": "your-key"
},
"enabled": true,
"timeout": 120000
}~/.codex/config.toml)[mcp_servers.tiktok]
command = "uvx"
args = ["tiktok-mcp-server"]
[mcp_servers.tiktok.env]
TRANSCRIBE_API_URL = "https://api.groq.com/openai/v1"
TRANSCRIBE_API_KEY = "your-key"uvx tiktok-mcp-server # stdio (what MCP clients launch)
uvx tiktok-mcp-server --transport streamable-http --host 127.0.0.1 --port 8000Inspect it interactively with the MCP Inspector:
npx @modelcontextprotocol/inspector uvx tiktok-mcp-serverA real browser (Playwright Chromium) opens TikTok's public pages, just like you would — no API keys or developer accounts
Profiles are read from the page's built-in data; search, discovery, and comments are read after the page finishes loading
Transcription: download the video → trim it to a small audio file → send it to your speech-to-text API → return the text
Logs go to stderr so the connection to your AI client stays clean
src/tiktokmcp/
├── __main__.py # python -m tiktokmcp
├── server.py # create_server() factory, instructions, CLI (--transport/--host/--port)
├── app.py # lifespan + AppContext (browser, scraper, transcriber)
├── config.py # Settings.from_env()
├── models.py # Pydantic result models -> outputSchema / structuredContent
├── errors.py # domain errors -> ToolError translation
├── validation.py # username / video-reference normalization
├── browser.py # BrowserManager: lazy Playwright Chromium, owned by the lifespan
├── scraper.py # TikTokScraper: profile JSON, video grids, search, comments
├── transcribe.py # Transcriber: yt-dlp -> ffmpeg -> speech-to-text API
└── tools/ # one module per tool, each exposing register(mcp)
├── _params.py # shared Annotated parameter types + ToolAnnotations
├── profile.py videos.py comments.py
└── search.py discover.py transcript.py
tests/ # pytest, in-memory MCP client (no network)Tool functions are thin: they validate input, pull shared services from the lifespan context, and return a typed model. Scraping and transcription logic lives in services that know nothing about MCP.
uv sync # install deps
uv run playwright install chromium # browser for the scraper
uv run pytest # offline test suite
uv run ruff check src tests && uv run ruff format src testsRead-only: no posting, liking, or any other write actions
TikTok may rate-limit or block scraping from some IPs; tools respond with an empty result + note rather than an error
get_comments can return nothing when TikTok hides comments from logged-out browsers
Transcription requires your own speech-to-text endpoint; nothing is relayed through third parties
MIT
Find TikTok creators posting about a topic. Searches the topic as a hashtag and returns unique creators with their profile URL and the video that surfaced them.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Maximum number of items to return (1-50). | |
| topic | Yes | Topic or hashtag, with or without '#' (e.g. 'skincare'). |
| Name | Required | Description |
|---|---|---|
| note | No | |
| count | Yes | |
| topic | Yes | |
| creators | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds real behavior: the topic is resolved as a hashtag search and results are deduplicated to unique creators, each tied to the video that surfaced them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no filler; the core action is front-loaded and the return behavior follows. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With annotations carrying the safety profile and an output schema covering the return structure, the description supplies the remaining essentials: hashtag-based search and creator deduplication. Minor gaps (pagination/ordering of results) are not material enough to block correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both 'topic' and 'count' fully documented including the '#'-optional form and the 1-50 range, so the baseline is 3. The description adds only the small semantic detail that the topic is searched as a hashtag, which the schema already hints at.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
It gives a specific verb and resource ('Find TikTok creators posting about a topic') plus the return shape (creators with profile URL and surfacing video). This implicitly separates it from search_videos, which returns videos rather than creators, though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the required 'topic' and the 'creators' framing signal when this is appropriate. There is no explicit when-to-use guidance versus search_videos or get_profile, and no stated exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get top-level comments on a TikTok video (author, text, likes). An empty list comes with a note when TikTok hides comments from logged-out browsers.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Maximum number of items to return (1-50). | |
| video_id | Yes | A TikTok video: full URL (tiktok.com, vm.tiktok.com short links accepted), '@user/video/<id>', or a bare numeric video id. |
| Name | Required | Description |
|---|---|---|
| note | No | |
| count | Yes | |
| comments | Yes | |
| video_url | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: an empty list comes with a note when TikTok hides comments from logged-out browsers, and 'top-level' signals replies are excluded. It stops short of mentioning auth or rate-limit behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero filler. The core capability is front-loaded and the caveat about hidden comments follows in the natural place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be re-explained, and both parameters are fully documented. The description covers the resource and a meaningful edge case; the only gap is explicit usage/routing guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% - video_id formats and count bounds are fully documented in the schema - so the baseline of 3 applies. The description adds no syntax, default, or format detail beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get top-level comments on a TikTok video') and names the returned fields (author, text, likes), which sets it apart from every sibling (get_profile, get_videos, search_videos, transcribe_video). The 'top-level' qualifier further scopes the operation precisely.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the name and resource, but there is no explicit when-to-use or when-not-to-use guidance, nor any routing to alternatives or prerequisites. It is adequate but leaves selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a TikTok user's public profile: nickname, bio, verified status, follower, following, like, and video counts, and avatar URL.
| Name | Required | Description | Default |
|---|---|---|---|
| username | Yes | TikTok handle, with or without the leading '@' (e.g. 'khaby.lame'). |
| Name | Required | Description |
|---|---|---|
| bio | No | |
| nickname | Yes | |
| username | Yes | |
| verified | No | |
| avatar_url | No | |
| like_count | No | |
| video_count | No | |
| follower_count | No | |
| following_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and reach profile is fully covered structurally. The description adds the field list but nothing about failure modes (private/deleted accounts) or rate limits, so with annotations doing the heavy lifting this is a 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the resource and its returned fields are stated immediately and nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described, yet the description restates them helpfully. Combined with full param coverage and complete annotations, the only missing piece is guidance on private or nonexistent accounts, which is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents the '@'-optional handle format with an example and length bounds. The description adds nothing about the parameter, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Get) and resource (TikTok user's public profile) and enumerates the returned fields, so the agent knows exactly what data comes back. It does not explicitly differentiate itself from siblings like discover_creators or get_videos, but the resource is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the name and the single-username parameter, but the description never states when to prefer this over discover_creators or other siblings, nor any prerequisite such as the account needing to be public. Adequate but with a clear routing gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a TikTok user's most recent public videos with id, caption, URL, and view count. Returns an empty list with a note if the account is private or TikTok blocks the request.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Maximum number of items to return (1-50). | |
| username | Yes | TikTok handle, with or without the leading '@' (e.g. 'khaby.lame'). |
| Name | Required | Description |
|---|---|---|
| note | No | |
| count | Yes | |
| videos | Yes | |
| username | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description goes beyond them by disclosing the failure/edge-case behavior: an empty list with a note when the account is private or TikTok blocks the request, which is genuinely useful for interpreting results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste, front-loaded with what the tool returns before the edge-case note. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so the return shape need not be re-explained, and the description handles the private/blocked edge case well. It is nearly complete for calling the tool correctly; only the sibling-routing context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters (count, username) are already documented in the schema. The description adds mild meaning via 'most recent' implying result ordering, but otherwise adds nothing beyond the structured fields. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (list) and resource (a TikTok user's most recent public videos) plus the fields returned. It is clearly distinguishable from siblings like get_profile (profile data) and search_videos (keyword search) because it is scoped to one user's recent uploads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrasing 'List a TikTok user's most recent public videos' implies the usage context, but there is no explicit when-to-use guidance and no mention of the alternative search_videos sibling for broader discovery. Usage is inferable but not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search TikTok videos by keyword or hashtag. Returns id, caption, URL, creator, and view count.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Maximum number of items to return (1-50). | |
| query | Yes | Search terms. Prefix with '#' to search a hashtag (e.g. '#booktok'). |
| Name | Required | Description |
|---|---|---|
| note | No | |
| count | Yes | |
| query | Yes | |
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered structurally. The description's remaining content (returned fields) duplicates the output schema rather than adding behavioral context such as pagination, rate limits, or result ordering. Some value, but not beyond structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero waste, with the core action and its input modes front-loaded before the return-value note. Appropriately sized for a simple two-parameter search.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a 100%-documented schema, full annotations, and an output schema covering return values, the description covers what an agent needs to invoke the tool. The only gap is routing guidance relative to the five sibling tools, which is a usage concern more than a completeness one.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the '#' hashtag prefix convention is already documented on the query parameter. The description's 'by keyword or hashtag' restates that schema content rather than extending it, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Search TikTok videos') and adds the scoping dimension ('by keyword or hashtag'), which lets an agent distinguish it from the sibling get_videos (profile-scoped fetch). It stops short of explicitly contrasting itself with the alternatives, so it is clear but not fully differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no exclusions, and no mention of the sibling tools (get_videos, discover_creators) that an agent must choose between. The only hint is the implied 'keyword/hashtag' scope, which the agent has to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transcribe a TikTok video's speech with the server's speech-to-text API. Returns the full text, language, duration, and word-level timestamps when the API supports them. Takes 10-60 seconds.
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | Optional ISO-639-1 language code (e.g. 'en', 'es') to skip auto-detection. | |
| video_url | Yes | A TikTok video: full URL (tiktok.com, vm.tiktok.com short links accepted), '@user/video/<id>', or a bare numeric video id. |
| Name | Required | Description |
|---|---|---|
| text | Yes | |
| model | Yes | Speech-to-text model that produced this transcript. |
| words | Yes | |
| duration | Yes | Audio duration in seconds. |
| language | Yes | |
| video_url | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: a 10-60 second latency window and the caveat that word-level timestamps are returned only 'when the API supports them,' which warns the agent about conditional output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero filler. The core action is front-loaded, and the return content plus latency caveat follow in order of importance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value structure need not be re-explained; annotations carry the safety semantics; and the description still supplies latency expectations and the conditional-timestamp caveat. Nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (video_url, language) are already fully documented in the schema, including accepted URL forms and the ISO-639-1 pattern. The description adds no additional parameter meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Transcribe a TikTok video's speech') and names the mechanism (server's speech-to-text API). No sibling tool (get_profile, get_videos, get_comments, search_videos, discover_creators) performs transcription, so the tool is unambiguously distinguishable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: an agent can infer it should call this when it needs spoken-word text from a video. There is no explicit when-to-use/when-not guidance, no alternative named, and no preconditions (e.g., public video, language availability) spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0discover_creatorsget_commentsget_profileget_videossearch_videostranscribe_videoScored across 6 tools
Most tools target distinct resources and actions: profile, videos, comments, search, creators, and transcription. The only mild overlap is between search_videos and discover_creators, since both search by topic/hashtag, but their output focus is clearly different (videos vs. creators).
All tool names follow a consistent verb_noun snake_case pattern: get_profile, get_videos, get_comments, search_videos, discover_creators, transcribe_video. The convention is predictable and readable throughout.
Six tools is well-scoped for a read-only TikTok data server, covering core retrieval and analysis needs without redundant operations. Each tool earns its place and the set is easy to navigate.
The surface covers profiles, user videos, comments, keyword search, creator discovery, and transcription, which handles most public TikTok research workflows. Minor gaps remain, such as no single-video lookup by ID or reply-level comments, but agents can work around these.
TikTok data for AI agents: videos, creators, sounds, hashtags, trends. Content + creator research.
TikTok data for agents: videos, creators, comments, search, transcripts. 25 tools, pay per call.
Public TikTok profiles, videos, comments and keyword search as JSON. No developer account.
Hosted MCP with 91 agent tools: X, domains, SEO, Maps, Trends, Search, YouTube, TikTok, and more.
