MCP servers give AI agents structured access to external data, but most ship with only web search or file system tools. Adding TikTok data endpoints lets agents research creators, analyze video performance, and monitor brand mentions directly within Claude, Cursor, or any MCP-compatible client. The Scavio TikTok API provides endpoints for user search, video search, profile data, user posts, video comments, and hashtag videos -- all through Bearer token authentication. This tutorial shows how to add TikTok tool definitions to an existing MCP server using the standard tool registration pattern.
Prerequisites
- An existing MCP server (Node.js or Python)
- A Scavio API key with TikTok access
- Basic understanding of MCP tool definitions
- Node.js 18+ or Python 3.10+
Walkthrough
Step 1: Define the TikTok API helper
Create a helper function that handles authentication and routing to the correct TikTok endpoint. All TikTok endpoints use POST with Bearer token auth.
import os
import requests
API_KEY = os.environ.get("SCAVIO_API_KEY", "your_scavio_api_key")
TIKTOK_BASE = "https://api.scavio.dev/api/v1/tiktok"
def tiktok_request(endpoint: str, payload: dict) -> dict:
r = requests.post(
f"{TIKTOK_BASE}/{endpoint}",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
},
json=payload
)
r.raise_for_status()
return r.json()Step 2: Register the search-users tool
Add a tool definition that lets the agent search for TikTok users by keyword. The tool accepts a query string and returns matching profiles.
# In your MCP server tool registration:
def handle_tiktok_search_users(params: dict) -> dict:
query = params.get("query", "")
results = tiktok_request("search-users", {"query": query})
return {"content": [{"type": "text", "text": json.dumps(results, indent=2)}]}
# Register with your MCP server:
# server.add_tool(
# name="tiktok_search_users",
# description="Search TikTok users by keyword",
# input_schema={"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]},
# handler=handle_tiktok_search_users
# )Step 3: Register video search and profile tools
Add tools for searching videos by keyword and fetching a user profile. These cover the most common agent research patterns.
def handle_tiktok_search_videos(params: dict) -> dict:
results = tiktok_request("search-videos", {"query": params["query"]})
return {"content": [{"type": "text", "text": json.dumps(results, indent=2)}]}
def handle_tiktok_profile(params: dict) -> dict:
results = tiktok_request("profile", {"username": params["username"]})
return {"content": [{"type": "text", "text": json.dumps(results, indent=2)}]}
def handle_tiktok_video_comments(params: dict) -> dict:
results = tiktok_request("video-comments", {"video_id": params["video_id"]})
return {"content": [{"type": "text", "text": json.dumps(results, indent=2)}]}Step 4: Update the MCP config to pass credentials
Add the SCAVIO_API_KEY environment variable to your MCP config file so the server has access to the TikTok endpoints at runtime.
// In .mcp.json or claude_desktop_config.json:
{
"mcpServers": {
"my-data-server": {
"command": "python",
"args": ["server.py"],
"env": {
"SCAVIO_API_KEY": "your_scavio_api_key"
}
}
}
}Python Example
import os
import json
import requests
API_KEY = os.environ.get("SCAVIO_API_KEY", "your_scavio_api_key")
TIKTOK_BASE = "https://api.scavio.dev/api/v1/tiktok"
def tiktok_request(endpoint: str, payload: dict) -> dict:
r = requests.post(
f"{TIKTOK_BASE}/{endpoint}",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
},
json=payload
)
r.raise_for_status()
return r.json()
def search_users(query: str) -> dict:
return tiktok_request("search-users", {"query": query})
def search_videos(query: str) -> dict:
return tiktok_request("search-videos", {"query": query})
def get_profile(username: str) -> dict:
return tiktok_request("profile", {"username": username})
def get_comments(video_id: str) -> dict:
return tiktok_request("video-comments", {"video_id": video_id})
def get_user_posts(username: str) -> dict:
return tiktok_request("user-posts", {"username": username})
if __name__ == "__main__":
users = search_users("productivity tips")
print(f"Found {len(users.get('users', []))} users")
videos = search_videos("ai tools 2026")
print(f"Found {len(videos.get('videos', []))} videos")JavaScript Example
const API_KEY = process.env.SCAVIO_API_KEY || "your_scavio_api_key";
const BASE = "https://api.scavio.dev/api/v1/tiktok";
async function tiktokRequest(endpoint, payload) {
const res = await fetch(`${BASE}/${endpoint}`, {
method: "POST",
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify(payload)
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
return res.json();
}
async function main() {
const users = await tiktokRequest("search-users", { query: "productivity tips" });
console.log(`Users: ${(users.users || []).length}`);
const videos = await tiktokRequest("search-videos", { query: "ai tools 2026" });
console.log(`Videos: ${(videos.videos || []).length}`);
const profile = await tiktokRequest("profile", { username: "charlidamelio" });
console.log(`Profile: ${profile.user?.nickname}`);
}
main().catch(console.error);Expected Output
{
"users": [
{
"username": "productivityguru",
"nickname": "Productivity Guru",
"followers": 284000,
"following": 150,
"likes": 1200000,
"bio": "Daily tips to get more done"
}
]
}