TikTok

You can search TikTok videos by hashtags and retrieve trending content through a dedicated MCP service. It handles anti-detection measures, proxies, and session management, so your Claude-based workflows can directly access relevant TikTok data or mock data when access is restricted.

How to use

You interact with this MCP server through an MCP client to perform hashtag-based video searches and gather video metadata. Use the search capability to specify hashtags and receive a list of videos with URLs, descriptions, and engagement statistics. You can control the number of results per search with a count that defaults to 30 if you omit it. The service also exposes a health endpoint to verify readiness and initialization status.

Typical usage patterns include: starting the service locally, configuring environment variables for TikTok access and proxy usage, and issuing search requests to retrieve video results for your Claude workflows. If TikTok blocks API access, the service transparently switches to mock data mode and marks such responses with a transformations note indicating simulated results.

To monitor health and ensure the service is ready to respond, perform a health check before sending search requests. The health status includes whether the API is initialized and the service name, version, and description.

How to install

# Prerequisites
- Python 3.8+
- Poetry (for Python dependency management)
- Playwright (for browser automation)

# Manual installation
# 1) Install dependencies
poetry install

# 2) Install browser automation dependencies
poetry run python -m playwright install

# 3) Start the service
poetry run python -m tiktok_mcp_service.main

Install via Smithery (automatic integration) to set up the TikTok MCP Service for Claude Desktop:

• Run the client install command exactly as shown below.

npx -y @smithery/cli install @terrylinhaochen/tiktok_mcp --client claude

Claude Desktop integration requires editable installation so you can manage the MCP from your environment. Use Poetry to install the service in editable mode and optionally give it a custom name.

# Navigate to the project directory
cd /path/to/tiktok-mcp-service

# Install the service in Claude Desktop with Poetry in editable mode
poetry run mcp install tiktok_mcp_service/main.py --with-editable . -f .env

# Optional: Install with a custom name
poetry run mcp install tiktok_mcp_service/main.py --name "TikTok Video Search" --with-editable . -f .env

Additional notes

The service uses environment variables for configuration. Create a .env file with optional values to optimize detection avoidance and proxy usage.

ms_token=your_tiktok_ms_token  # Optional but recommended to avoid bot detection
TIKTOK_PROXY=your_proxy_url    # Optional proxy configuration

Available tools

TikTokApi

Library used to interact with TikTok data endpoints for video search and metadata extraction.

FastMCP

Framework powering the MCP server runtime and endpoint management.

Playwright

Browser automation tool used for interacting with web interfaces when needed.

Poetry

Dependency management tool used to install and manage Python packages for the service.