TikTok MCP Server

Model Context Protocol (MCP) server for TikTok. Provides tools for searching videos, users, hashtags, getting trending content, user profiles, video details, and more.

Features

• Video Search - Search TikTok videos by keyword

• Trending Hashtags - Get currently trending hashtags by region

• Trending Videos - Get popular/trending videos

• User Info - Get user profile details (followers, following, likes, bio, etc.)

• User Videos - Get videos from a specific user's profile

• Video Details - Get detailed video information (stats, description, etc.)

• Hashtag Search - Get videos for a specific hashtag

• User Search - Search for TikTok users

Related MCP server: TikTok MCP Server

API Access

This server supports two modes:

1. Official TikTok API (recommended) - Requires approved developer access with:

   • TIKTOK_CLIENT_KEY

   • TIKTOK_CLIENT_SECRET

   • TIKTOK_ACCESS_TOKEN

2. Public Scraping (fallback) - Works without API credentials but may be rate-limited or break if TikTok changes their frontend.

Transport

The server runs over streamable-HTTP by default, exposing the MCP endpoint at /mcp so it can be hosted as a network service (Easypanel/Docker). Set MCP_TRANSPORT=stdio to run over stdio for local subprocess use instead.

Configuration

Environment variables:

Official API (Recommended)

Get credentials from TikTok Developers and set the three TIKTOK_* variables. If they are not set, the server falls back to public scraping.

Local Development

# Install (editable) with uv
uv pip install -e .

# Run (streamable-HTTP on http://0.0.0.0:8000/mcp)
tiktok-mcp

# Or over stdio
MCP_TRANSPORT=stdio tiktok-mcp

Docker

docker build -t tiktok-mcp .
docker run -p 8000:8000 \
  -e TIKTOK_CLIENT_KEY=... \
  -e TIKTOK_CLIENT_SECRET=... \
  -e TIKTOK_ACCESS_TOKEN=... \
  tiktok-mcp

The MCP endpoint will be available at http://localhost:8000/mcp.

Deploy on Easypanel

1. Create an App service pointing to this repository (or the GHCR image built by the included CI workflow).

2. Build method: Dockerfile (already in the repo root).

3. Set the exposed/container port to 8000 and add a domain (Easypanel handles SSL).

4. Add the TIKTOK_* environment variables under the service's Environment tab (leave them empty to use public scraping).

5. Deploy. The MCP endpoint will be served at https://<your-domain>/mcp.

Connecting an MCP client

For a hosted HTTP server, connect via URL (not a spawned command). The exact config file depends on the client; the shape is the same:

{
  "mcpServers": {
    "tiktok": {
      "url": "https://<your-domain>/mcp"
    }
  }
}

• Claude Desktop / Claude Code: add the block above to the MCP config and restart.

• Hermes Agent: point the tiktok server at the same url.

Once connected, the tools appear to the model (e.g. mcp_tiktok_search_videos) and can be triggered with natural language — see Example Queries.

Verify the endpoint

After running locally or deploying, confirm the server is up with a raw MCP handshake. The streamable-HTTP endpoint requires both application/json and text/event-stream in the Accept header:

curl -i -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

A healthy server returns HTTP/1.1 200 OK and an SSE data: line containing "serverInfo":{"name":"tiktok-mcp",...}.

Available Tools

All tools return a JSON text payload. When scraping is used (no official API credentials), responses include a "source": "scraping" field.

Example Queries

• "Search for videos about AI automation"

• "Get trending hashtags in Brazil"

• "Find trending videos in the US"

• "Get profile info for @username"

• "Get videos from @username's profile"

• "Search for #marketing hashtag videos"

• "Find users about 'dark fantasy art'"

Development

# Install with dev dependencies
uv pip install -e ".[dev]"

Note: an automated test suite is not included yet. Use the Verify the endpoint handshake to smoke-test changes.

Important Notes

• Rate Limits: Public scraping is subject to TikTok's rate limits. Use official API for production.

• Legal: Respect TikTok's Terms of Service and robots.txt

• Stability: Public scraping may break if TikTok changes their frontend structure

• Official API: Requires TikTok developer approval - apply at developers.tiktok.com

License

MIT