{"skill":{"slug":"tiktok-search","displayName":"TikTok Search","summary":"Search TikTok videos and run product, trend, competitor, and content insights through Gecho Bridge MCP. Use for TikTok keyword research, trending video disco...","description":"---\nname: tiktok-search\ndescription: Search TikTok videos and run product, trend, competitor, and content insights through Gecho Bridge MCP. Use for TikTok keyword research, trending video discovery, winning-product analysis, and checking async insight jobs. Requires the Gecho Chrome extension, an active TikTok session, and the shared Gecho Bridge MCP server.\nmetadata:\n  openclaw:\n    os: [\"darwin\", \"linux\", \"win32\"]\n    requires:\n      bins: [\"node\", \"npx\"]\n  hermes:\n    tags: [tiktok, search, insight, gecho, mcp]\n    category: social-media\n    os: [darwin, linux, windows]\n---\n\n# TikTok Search & Insight by Gecho\n\nSearch TikTok from an AI chat, collect structured video metadata, and run async product or trend insight jobs through the official Gecho Bridge MCP workflow.\n\nThis is the default TikTok aggregate Skill for Gecho. It covers the TikTok video search and TikTok insight workflow. Single-tool TikTok Skills may exist for distribution and search traffic, but this Skill is the recommended default for users who want the complete TikTok research workflow.\n\n## Critical prerequisite: read before use\n\nGecho Skills must be used with the Gecho Chrome extension. You must be logged in to both your Gecho account in the extension and TikTok in the Chrome web app. If either login is missing, all TikTok search and insight features may fail even though the Skill is installed.\n\n## 3-step quick start\n\n### Step 1: Install the Gecho Chrome extension\n\n1. Open the [Gecho Chrome extension download page](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb).\n2. Click `Add to Chrome`, then confirm `Add extension`.\n\n### Step 2: Log in to the Gecho extension\n\nOpen the Gecho extension in Chrome and log in to your Gecho account. Keep the extension online.\n\n### Step 3: Log in to TikTok web\n\nOpen TikTok in Chrome and log in to the TikTok web app. Keep the logged-in TikTok tab open.\n\nAfter setup is complete, return to the OpenClaw dashboard or Hermes and ask: \"Search xxx on TikTok\". For example: \"Search hamburgers on TikTok\".\n\n## Official links and setup help\n\n- Website: [gecho.ai](https://gecho.ai/)\n- GitHub: [gecho-ai/gecho-bridge](https://github.com/gecho-ai/gecho-bridge)\n- YouTube channel: [@Gecho-AI](https://www.youtube.com/@Gecho-AI)\n- Chrome extension: [Gecho Extension](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb)\n- OpenClaw setup video: [OpenClaw + TikTok: Direct AI Browser Control via Gecho Bridge](https://www.youtube.com/watch?v=ggwY9hISHcQ)\n- Hermes setup video: [Hermes + TikTok: Direct AI Browser Control via Gecho Bridge](https://www.youtube.com/watch?v=zHKnuWnxt_c)\n- Discord: [https://discord.gg/RFDVZMR6Tn](https://discord.gg/RFDVZMR6Tn)\n- WeCom group QR code: [qywx.jpg](https://github.com/gecho-ai/gecho-bridge/blob/main/qywx.jpg)\n\n## What this skill does\n\n- Finds high-performing TikTok videos for a keyword.\n- Collects titles, authors, engagement data, and video links.\n- Saves full raw result sets to a local JSON file.\n- Starts async insight jobs for product research, competitor analysis, and trend discovery.\n\nBest-fit prompts:\n\n- \"Search TikTok for portable blender and show the top liked videos.\"\n- \"Find winning hooks for cat toy videos.\"\n- \"Run product opportunity insight for outdoor picnic mat.\"\n- \"Check the status of my previous TikTok insight job.\"\n\n## Important: Skill-only install is not enough\n\nThis Skill is the instruction layer. It tells the AI when and how to use Gecho.\n\nTo actually run TikTok searches, the user also needs:\n\n- the Gecho Bridge MCP server\n- the Gecho Chrome extension\n- Chrome with TikTok logged in\n- the Gecho extension logged in to a Gecho account and online\n\nIf the user installed only this Skill from ClawHub, searches will not work until the Gecho Bridge MCP server is configured. In that case, use the MCP setup path below.\n\nAlready installed Gecho Bridge? If `@gecho-ai/gecho-bridge-bundle` is installed and the Gecho MCP tools are visible, no extra MCP setup is needed for this Skill.\n\n## Quick start\n\n### OpenClaw Skill install: configure MCP\n\nIf this Skill is already installed in OpenClaw, configure the Gecho Bridge MCP server once:\n\n```bash\nopenclaw mcp set gecho-bridge '{\"command\":\"npx\",\"args\":[\"-y\",\"@gecho-ai/gecho-bridge@latest\"]}'\nopenclaw gateway restart\n```\n\nThen verify:\n\n```bash\nopenclaw mcp list\n```\n\n### Optional: OpenClaw Bundle Plugin\n\nIf the user has not installed this Skill yet and prefers plugin management, the bundle plugin can install Gecho with the MCP entry configured:\n\n```bash\nopenclaw plugins install clawhub:@gecho-ai/gecho-bridge-bundle\nopenclaw gateway restart\n```\n\nTo upgrade later:\n\n```bash\nopenclaw plugins update clawhub:@gecho-ai/gecho-bridge-bundle\nopenclaw gateway restart\n```\n\n### Hermes setup\n\n```bash\nhermes mcp add gecho-bridge --command npx --args=\"-y\" --args=\"@gecho-ai/gecho-bridge@latest\"\nhermes restart\n```\n\nIf Hermes cannot find `npx` even though Node.js is installed, use the absolute `npx` path. On many macOS Homebrew installs this is:\n\n```bash\nhermes mcp add gecho-bridge --command /opt/homebrew/bin/npx --args=\"-y\" --args=\"@gecho-ai/gecho-bridge@latest\"\nhermes restart\n```\n\n## First-run checklist\n\nBefore the first search, make sure:\n\n- Node.js `>= 18` is available.\n- The [Gecho Chrome extension](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb) is installed.\n- Chrome is open with TikTok logged in.\n- The Gecho extension is logged in to a Gecho account and online.\n- The TikTok tab is not blocked by CAPTCHA, login walls, or a frozen page.\n\nFull setup guide:\n[Gecho Bridge README](https://github.com/gecho-ai/gecho-bridge/blob/main/README.md)\n\nFor videos and support links, see the official links section above.\n\n## Tool choice\n\n| User goal | Use tool | Notes |\n|---|---|---|\n| Search TikTok videos and collect metadata | `tiktok_search` | Returns results directly |\n| Analyze a niche, product, trend, or competitor opportunity | `tiktok_insight` | Starts an async job and returns a `jobId` |\n| Check an existing async insight job | `check_insight_status` | Use the `jobId` returned by `tiktok_insight` |\n\nUse this aggregate Skill for broad TikTok research requests. If the user explicitly asks for one exact raw tool only, such as \"run tiktok_search\", a matching single-tool distribution Skill may be used instead when available.\n\n## Official MCP tools\n\n### `tiktok_search`\n\nSearches TikTok for a keyword, scrolls the page through the Gecho browser extension, returns structured metadata, and saves the full result set.\n\nParameters:\n\n- `query` string, required: search keyword or phrase.\n- `save_dir` string, optional: absolute directory path for saving results. Do not pass a `.json` filename. Omit this parameter if no reliable absolute directory is available.\n\nExpected result:\n\n- A JSON array of video metadata, plus a saved local file path when results are written successfully.\n\n### `tiktok_insight`\n\nStarts an asynchronous TikTok insight job for product, trend, or competitor research.\n\nParameters:\n\n- `query` string, required: search keyword or product/category phrase.\n- `save_dir` string, optional: absolute directory path for saving results. Do not pass a `.json` filename. Omit this parameter if no reliable absolute directory is available.\n\nExpected result:\n\n- A `jobId`. The final result must be checked later with `check_insight_status`.\n\n### `check_insight_status`\n\nChecks the status or final result of an existing insight job.\n\nParameters:\n\n- `jobId` string, required: the job ID returned by `tiktok_insight`.\n\nExpected result:\n\n- `running`, `error`, or completed insight data.\n\n## Agent execution rules\n\nUse this Skill before calling any Gecho TikTok MCP tool when the user asks to search TikTok, find trending videos, analyze competitors, collect TikTok metadata, discover winning products, or research keyword trends.\n\nCore rules:\n\n- Use only the official Gecho MCP tools: `tiktok_search`, `tiktok_insight`, and `check_insight_status`.\n- Do not replace Gecho with WebSearch, browser automation, terminal scrapers, mcporter, unofficial APIs, or hand-written TikTok scraping.\n- Do not start more than one Gecho scraping or insight job in the same conversational turn.\n- Do not run Gecho scraping jobs in parallel because the workflow depends on one live browser tab and extension session.\n- If a tool fails, times out, or returns an error, stop and report the exact failure reason.\n- If `tiktok_search` returns no items, do not rewrite, translate, broaden, or retry the keyword automatically.\n- If `tiktok_insight` starts successfully, report the `jobId` and explain that the user should check status later.\n- If `check_insight_status` says the job is still running, tell the user to wait before checking again.\n- If the official Gecho MCP tools are unavailable in the current session, provide setup instructions instead of probing the environment.\n- On first-run setup guidance, missing MCP tools, extension/session problems, timeouts, save failures, or any tool error, include the setup and support links block below.\n- Do not add the setup and support links block to normal successful search or insight responses unless the user asks for setup help.\n- Do not configure, edit, repair, or rewrite OpenClaw/Hermes/MCP settings on the user's behalf. Provide the setup commands and ask the user to run or approve them outside the tool workflow.\n- Do not use this Skill for TikTok Shop, X/Twitter, Amazon, or other platform workflows; those should have their own Gecho aggregate Skills.\n\nAllowed status behavior:\n\n- A user may explicitly ask to check one existing `jobId`; in that case, call `check_insight_status` once.\n- Do not start a new `tiktok_search` or `tiktok_insight` job in the same turn after checking status unless the user asks again in a later turn.\n\n## Standard workflows\n\n### Search workflow\n\n1. Use the exact keyword requested by the user.\n2. If the user did not provide `save_dir`, choose a safe absolute directory path in the current workspace. If no reliable absolute directory is available, omit `save_dir` and let Gecho use its default data directory.\n3. Call `tiktok_search`.\n4. If the result is empty, say that the exact keyword returned no results and stop.\n5. If results are present, summarize only the top 3 to 5 items and provide the saved file path.\n\n### Insight workflow\n\n1. Use the exact product, niche, or keyword requested by the user.\n2. If the user did not provide `save_dir`, choose a safe absolute directory path in the current workspace. If no reliable absolute directory is available, omit `save_dir` and let Gecho use its default data directory.\n3. Call `tiktok_insight`.\n4. Report the returned `jobId`.\n5. Tell the user the job may take several minutes and should be checked later with `check_insight_status`.\n\n### Status workflow\n\n1. Call `check_insight_status` with the provided `jobId`.\n2. If still running, report the current status and recommend waiting about 60 seconds.\n3. If completed, summarize the key findings and provide the saved file path.\n4. If failed, report the exact error and stop.\n\n## Setup and support links block\n\nUse this compact block on first-run guidance and all setup or failure responses. Keep it near the end of the answer, after the exact fix.\n\n````markdown\nHelpful Gecho links:\n\n- Website: https://gecho.ai/\n- YouTube channel: https://www.youtube.com/@Gecho-AI\n- OpenClaw setup video: https://www.youtube.com/watch?v=ggwY9hISHcQ\n- Hermes setup video: https://www.youtube.com/watch?v=zHKnuWnxt_c\n- GitHub and README: https://github.com/gecho-ai/gecho-bridge\n- Support: Discord https://discord.gg/RFDVZMR6Tn, WeCom QR https://github.com/gecho-ai/gecho-bridge/blob/main/qywx.jpg\n````\n\n## Setup-missing response\n\nUse this when the official Gecho MCP tools are not available, or when the user only installed the Skill and cannot run searches yet.\n\nUse the template below as the canonical setup-missing response. The agent may translate the prose to match the user's language, but must not summarize it into a shorter checklist unless the user explicitly asks for a short version.\n\nRequired content that must not be omitted:\n\n- State that Gecho Bridge MCP is not configured and the Skill alone cannot run TikTok.\n- Include all 3 requirements: MCP configured, Gecho Chrome extension installed and logged in, TikTok web logged in and tab kept open.\n- Include the OpenClaw MCP setup command and `openclaw mcp list` verification command.\n- Include the Chrome extension link.\n- Include after-setup wording that tells the user to return to OpenClaw Dashboard or Hermes and retry the request.\n- Include all related links: website, OpenClaw setup video, Hermes setup video, YouTube channel, GitHub/README, Discord, and WeCom QR code.\n- Include related Gecho Skills listed in the template.\n- Do not recommend `openclaw plugins install` in this setup-missing response.\n\n````markdown\nGecho Bridge is not ready yet.\n\nThis Skill is installed, but the official Gecho Bridge MCP tools are not available in this session yet. Installing the Skill alone does not start the TikTok search service.\n\nGecho requires all 3 items below before TikTok search or insight can run:\n\n1. Gecho Bridge MCP is configured.\n2. The Gecho Chrome extension is installed and logged in to a Gecho account.\n3. TikTok web is logged in inside Chrome, with the TikTok tab kept open.\n\nFollow these first-time setup steps:\n\n**1. Install the Gecho Chrome extension**\n\nChrome Web Store:\nhttps://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb\n\nAfter installing, open the extension and log in to your Gecho account.\n\n**2. Configure Gecho Bridge MCP**\n\nOpenClaw MCP setup:\n\n```bash\nopenclaw mcp set gecho-bridge '{\"command\":\"npx\",\"args\":[\"-y\",\"@gecho-ai/gecho-bridge@latest\"]}'\nopenclaw gateway restart\n```\n\nThen verify:\n\n```bash\nopenclaw mcp list\n```\n\nFor Hermes:\n\n```bash\nhermes mcp add gecho-bridge --command npx --args=\"-y\" --args=\"@gecho-ai/gecho-bridge@latest\"\nhermes restart\n```\n\n**3. Log in to TikTok web**\n\nOpen TikTok in Chrome, log in, and keep the logged-in TikTok tab open.\n\nAfter setup, return to OpenClaw Dashboard or Hermes and ask again, for example:\n\"Search computers on TikTok\"\n\n\n**Related links**\n\n- Website: https://gecho.ai/\n- OpenClaw setup video: https://www.youtube.com/watch?v=ggwY9hISHcQ\n- Hermes setup video: https://www.youtube.com/watch?v=zHKnuWnxt_c\n- YouTube channel: https://www.youtube.com/@Gecho-AI\n- GitHub and README: https://github.com/gecho-ai/gecho-bridge\n- Discord support: https://discord.gg/RFDVZMR6Tn\n- WeCom QR code: https://github.com/gecho-ai/gecho-bridge/blob/main/qywx.jpg\n\n**Related Gecho Skills**\n\n- `tiktok-video-search`: TikTok video search and metadata collection.\n- `tiktok-insight`: TikTok product, trend, competitor, and content insight jobs.\n- `tiktok-search`: complete TikTok search and insight workflow.\n````\n\n## Troubleshooting\n\n| Situation | What to do |\n|---|---|\n| MCP tools are missing | Give the setup-missing response. Do not run local shell probes. |\n| User installed only the Skill | Explain that Skill-only install is not enough and provide the OpenClaw MCP setup command. |\n| Hermes MCP tools are missing | Provide the `hermes mcp add ...` command. Do not inspect or rewrite Hermes config files. |\n| Extension not connected | Ask the user to enable/login to the Gecho Chrome extension and keep a logged-in TikTok tab open. |\n| CAPTCHA or login wall | Ask the user to resolve it manually in Chrome, then retry in a later turn. |\n| Request timeout | Report the timeout, mention stuck page/network/CAPTCHA as likely causes, and stop. |\n| Empty search results | Say the exact keyword returned no results and ask the user to choose another keyword manually. |\n| Insight still running | Report running status and recommend checking again after about 60 seconds. |\n| Failed to save results | Ask the user to provide a valid absolute directory path with write permission. |\n\n## FAQ\n\n### Why is the Chrome extension required? Can't I just use the web page?\n\nGecho needs real-time platform data from a live browser session, such as TikTok videos and other platform data in Gecho workflows. The Chrome extension connects the AI workflow to the user's logged-in Chrome session; the Skill page alone cannot collect this data.\n\n### Why do I need to log in to TikTok? Can I use it without login?\n\nTikTok limits content access for logged-out users. After you log in, the extension can access the complete data available in your browser session, such as video captions/scripts, comments, engagement data, and other signals when available.\n\nGecho does not ask for or collect your TikTok password, private account information, or publish anything on your behalf.\n\n### Need help?\n\nScan the [WeCom QR code](https://github.com/gecho-ai/gecho-bridge/blob/main/qywx.jpg) for 1:1 support.\n\n## Output guidelines\n\nFor successful search:\n\n- Say the search completed.\n- Include total result count if available.\n- Include saved file path if available.\n- Show top 3 to 5 results only.\n- Do not paste the full raw JSON into chat.\n\nFor successful insight start:\n\n- Say the insight job started.\n- Include the `jobId`.\n- Include expected saved path if available.\n- Tell the user to check status later.\n\nFor completed insight:\n\n- Summarize key findings.\n- Include saved file path.\n- Avoid claiming conclusions not supported by returned tool data.\n\nFor failures:\n\n- Report the exact tool error or failure state.\n- Provide only the relevant fix from Troubleshooting.\n- Include the setup and support links block so the user can continue setup through docs, videos, or support.\n- Do not retry in the same turn.\n\n## Scope and limits\n\nThis Skill should:\n\n- Help users complete the official Gecho setup when prerequisites are missing.\n- Route TikTok search and insight requests to the official Gecho MCP tools.\n- Keep search, insight, and status-check flows explicit.\n- Summarize results without flooding the chat.\n\nThis Skill must never:\n\n- Pretend the Skill page alone is enough when MCP is missing.\n- Pretend `tiktok_insight` is synchronous.\n- Use unofficial TikTok scraping workflows.\n- Invent results when the tool returns no data.\n- Solve CAPTCHA, log in to TikTok, or operate the user's browser outside the official Gecho MCP workflow.\n","tags":{"latest":"1.1.24"},"stats":{"comments":0,"downloads":603,"installsAllTime":23,"installsCurrent":1,"stars":4,"versions":6},"createdAt":1778322574116,"updatedAt":1780756109312},"latestVersion":{"version":"1.1.24","createdAt":1780756109312,"changelog":"**Changelog for tiktok-search v1.1.24**\n\n- The setup section was rewritten for greater clarity and simplicity, emphasizing the three critical steps to enable the Skill (install Gecho Chrome extension, log in to Gecho extension, log in to TikTok).\n- More explicit warnings and instructions were added about required extension and account logins for proper operation.\n- Minor language and formatting improvements were made for better readability.\n- The file skill-card.md was removed.","license":"MIT-0"},"metadata":{"setup":[],"os":["darwin","linux","win32"],"systems":null},"owner":{"handle":"gecho-ai","userId":"s175fhc7pkv1bdmpprb4xxy1ch86dc5q","displayName":"Gecho AI","image":null},"moderation":null}