tiktok_search
Search TikTok videos by keywords or hashtags to find content with detailed metadata. Get video details like creator, engagement metrics, creation date, and subtitles. Use pagination to continue searches efficiently.
Instructions
Search for TikTok videos based on a query.This is used for searching TikTok videos by keywords, hashtags, or other search terms.Supports search query as input and optional cursor and search_uid for pagination.Returns a list of videos matching the search criteria with their details including - Description, video ID, creator, hashtags, engagement metrics, date of creation, duration of the video and available subtitles with language and source information - Pagination metadata for continuing the search
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | Pagination cursor for getting more results (optional) | |
| query | Yes | Search query for TikTok videos, e.g., 'funny cats', 'dance', 'cooking tutorial' | |
| search_uid | No | Search session identifier for pagination (optional) |
Implementation Reference
- index.ts:357-368 (handler)Handler case in the CallToolRequestSchema that handles the tiktok_search tool call: validates input arguments using isSearchArgs and invokes the performSearch function to execute the tool logic.case "tiktok_search": { if (!isSearchArgs(args)) { throw new Error("Invalid arguments for tiktok_search"); } const { query, cursor, search_uid } = args; const results = await performSearch(query, cursor, search_uid); return { content: [{ type: "text", text: results }], isError: false, }; }
- index.ts:63-90 (schema)Tool schema definition for 'tiktok_search' specifying name, description, and input schema with required 'query' and optional pagination fields.const SEARCH: Tool = { name: "tiktok_search", description: "Search for TikTok videos based on a query." + "This is used for searching TikTok videos by keywords, hashtags, or other search terms." + "Supports search query as input and optional cursor and search_uid for pagination." + "Returns a list of videos matching the search criteria with their details including" + " - Description, video ID, creator, hashtags, engagement metrics, date of creation, duration of the video and available subtitles with language and source information" + " - Pagination metadata for continuing the search", inputSchema: { type: "object", properties: { query: { type: "string", description: "Search query for TikTok videos, e.g., 'funny cats', 'dance', 'cooking tutorial'", }, cursor: { type: "string", description: "Pagination cursor for getting more results (optional)", }, search_uid: { type: "string", description: "Search session identifier for pagination (optional)", }, }, required: ["query"], }, };
- index.ts:200-252 (helper)Core helper function that executes the tiktok_search logic: constructs API request to TikNeuron search endpoint, fetches results, formats video details and pagination metadata into text response.async function performSearch(query: string, cursor?: string, search_uid?: string) { const url = new URL('https://tikneuron.com/api/mcp/search'); url.searchParams.set('query', query); if (cursor) { url.searchParams.set('cursor', cursor); } if (search_uid) { url.searchParams.set('search_uid', search_uid); } const response = await fetch(url, { headers: { 'Accept': 'application/json', 'Accept-Encoding': 'gzip', 'MCP-API-KEY': TIKNEURON_MCP_API_KEY, } }); if (!response.ok) { throw new Error(`TikNeuron API error: ${response.status} ${response.statusText}\n${await response.text()}`); } const data = await response.json() as SearchResult; if (data.videos && data.videos.length > 0) { const videosList = data.videos.map((video, index) => { return `Video ${index + 1}: Description: ${video.description || 'N/A'} Video ID: ${video.video_id || 'N/A'} Creator: ${video.creator || 'N/A'} Hashtags: ${Array.isArray(video.hashtags) ? video.hashtags.join(', ') : 'N/A'} Likes: ${video.likes || '0'} Shares: ${video.shares || '0'} Comments: ${video.comments || '0'} Views: ${video.views || '0'} Bookmarks: ${video.bookmarks || '0'} Created at: ${video.created_at || 'N/A'} Duration: ${video.duration || 0} seconds Available subtitles: ${video.available_subtitles?.map(sub => `${sub.language || 'Unknown'} (${sub.source || 'Unknown source'})`).join(', ') || 'None'}`; }).join('\n\n'); const metadata = `\nSearch Metadata: Cursor: ${data.metadata?.cursor || 'N/A'} Has more results: ${data.metadata?.has_more ? 'Yes' : 'No'} Search UID: ${data.metadata?.search_uid || 'N/A'}`; return videosList + metadata; } else { return 'No videos found for the search query'; } }
- index.ts:189-198 (helper)Type guard helper function for validating the input arguments of the tiktok_search tool.function isSearchArgs(args: unknown): args is { query: string, cursor?: string, search_uid?: string } { return ( typeof args === "object" && args !== null && "query" in args && typeof (args as { query: string }).query === "string" && ("cursor" in args ? typeof (args as { cursor?: string }).cursor === "string" : true) && ("search_uid" in args ? typeof (args as { search_uid?: string }).search_uid === "string" : true) ); }
- index.ts:318-320 (registration)Registration of available tools list in ListToolsRequestSchema handler, including the tiktok_search tool (named SEARCH).server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [GET_SUBTITLE, GET_POST_DETAILS, SEARCH], }));