tiktok

A Model Context Protocol service for TikTok video discovery and metadata extraction.

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

Command

claude mcp add --transport stdio yap-audio-tiktok-mcp python -m tiktok_mcp_service.main \
  --env ms_token="Optional but recommended to avoid bot detection" \
  --env TIKTOK_PROXY="Optional proxy configuration"

How to use

This TikTok MCP Service provides a programmatic interface to discover TikTok videos by hashtags and retrieve associated metadata. It exposes an API with endpoints for health checks and searching content, incorporating anti-detection measures, proxy support, automatic API session management, and rate limiting/error handling to maintain stability during scraping and data extraction. Once running, you can use the /health endpoint to confirm the service is initialized, and the /search endpoint to query videos by hashtags with a configurable result count. The service relies on TikTokApi and browser automation to fetch data while mitigating bot-detection challenges, making it suitable for application-level discovery and metadata gathering rather than real-time user browsing.

How to install

Prerequisites:

Python 3.8+ installed on your system
Poetry for dependency management

Installation steps:

Clone or open the project directory containing the TikTok MCP Service.
Install dependencies using Poetry:

poetry install

Install browser automation dependencies (Playwright):

poetry run python -m playwright install

Create a .env file with optional configuration (see below) and start the service:

cp .env.example .env  # if an example is provided; otherwise create .env
poetry run python -m tiktok_mcp_service.main

If integrating with Claude Desktop, install/edit the service through Poetry as shown in the Claude integration section of the README, ensuring commands run under Poetry for dependency management.

Environment configuration (example):

ms_token=your_tiktok_ms_token # Optional but recommended
TIKTOK_PROXY=your_proxy_url # Optional proxy configuration

Note: The exact package names and entry points depend on how the project exposes the MCP service within the tiktok_mcp_service package.

Additional notes

Tips and considerations:

Keep ms_token in a secure, private environment variable to minimize detection risks.
If using proxies, rotate or pool proxies to reduce IP-blocking chances.
Monitor health via the /health endpoint to ensure API initialization and readiness before heavy usage.
The /search endpoint accepts hashtags and a count parameter (default 30) to control result volume; tune this based on rate limits and performance.
Ensure Playwright browsers are properly installed in the environment to support any headless automation required by the TikTok API wrapper.
When migrating environments (dev, staging, prod), maintain separate .env configurations to prevent token leakage across environments.