TikTok MCP Service is a Model Context Protocol service that allows you to search for TikTok videos by hashtags and extract metadata. The service includes anti-detection measures and robust error handling to ensure reliable access to TikTok content.
The service uses environment variables for configuration. Create a .env file with:
ms_token=your_tiktok_ms_token # Optional but recommended to avoid bot detection
TIKTOK_PROXY=your_proxy_url # Optional proxy configuration
To install and run the TikTok MCP Service:
# Install dependencies
poetry install
# Install browser automation dependencies
poetry run python -m playwright install
# Start the service
poetry run python -m tiktok_mcp_service.main
To integrate the service with Claude Desktop:
# 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
The health check endpoint allows you to verify the service is running properly:
GET /health
Example response:
{
"status": "running",
"api_initialized": true,
"service": {
"name": "TikTok MCP Service",
"version": "0.1.0",
"description": "A Model Context Protocol service for searching TikTok videos"
}
}
To search for videos with specific hashtags:
POST /search
Request body:
{
"search_terms": ["python", "coding"],
"count": 30
}
The count parameter is optional and defaults to 30 videos.
The response includes video URLs, descriptions, and engagement statistics (views, likes, shares, comments).
To clean up resources and API sessions:
POST /cleanup
The service includes error handling for various scenarios:
If you encounter errors, check your ms_token and proxy configuration to ensure they're valid and active.
There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.
If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.
To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".
When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:
{
"mcpServers": {
"cursor-rules-mcp": {
"command": "npx",
"args": [
"-y",
"cursor-rules-mcp"
]
}
}
}
To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.
Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.
The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.
You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.