TikTok MCP Server

Instructions

Implementation Reference

• tiktok_mcp/browser.py:460-460 (handler)

  This is the definition of the `explore_hashtag` method in `TikTokBrowser`.

  async def explore_hashtag(self, hashtag: str, count: int = 10) -> dict:

• tiktok_mcp/browser.py:460-518 (handler)

  Full implementation of `explore_hashtag` in `TikTokBrowser` that performs the actual browser interactions for the `tiktok_hashtag` tool.

  async def explore_hashtag(self, hashtag: str, count: int = 10) -> dict:
      """Explore videos for a specific hashtag."""
      tag = hashtag.lstrip("#")
      page = await self.goto_tiktok(f"/tag/{tag}")
      await asyncio.sleep(3)
  
      # Get hashtag stats
      tag_info = await page.evaluate("""() => {
          const title = document.querySelector('[data-e2e="challenge-title"]') || document.querySelector('h1');
          const views = document.querySelector('[data-e2e="challenge-vvcount"]') || document.querySelector('[class*="StyledStatValue"]');
          return {
              hashtag: title?.textContent?.trim() || '',
              views: views?.textContent?.trim() || '',
          };
      }""")
  
      videos = []
      seen_ids = set()
      scroll_attempts = 0
  
      while len(videos) < count and scroll_attempts < count * 2:
          items = await page.evaluate("""() => {
              const videos = [];
              const cards = document.querySelectorAll('[data-e2e="challenge-item"], [class*="DivItemContainer"]');
              cards.forEach(card => {
                  try {
                      const link = card.querySelector('a[href*="/video/"]');
                      const desc = card.querySelector('[title]') || card.querySelector('[class*="SpanText"]');
                      const views = card.querySelector('[class*="video-count"]') || card.querySelector('strong');
                      
                      const href = link?.href || '';
                      const videoIdMatch = href.match(/video\\/([0-9]+)/);
                      
                      videos.push({
                          video_id: videoIdMatch ? videoIdMatch[1] : null,
                          url: href,
                          description: desc?.title || desc?.textContent?.trim() || '',
                          views: views?.textContent?.trim() || '',
                      });
                  } catch(e) {}
              });
              return videos;
          }""")
  
          for item in items:
              vid = item.get("video_id")
              if vid and vid not in seen_ids:
                  seen_ids.add(vid)
                  videos.append(item)
  
          await page.evaluate("window.scrollBy(0, 600)")
          await asyncio.sleep(random.uniform(1.0, 2.0))
          scroll_attempts += 1
  
      return {
          "hashtag_info": tag_info,
          "videos": videos[:count],
      }

• tiktok_mcp/server.py:247-252 (handler)

  The tool handler in `server.py` that dispatches the `tiktok_hashtag` call to the browser implementation.

  elif name == "tiktok_hashtag":
      results = await browser.explore_hashtag(
          arguments["hashtag"],
          arguments.get("count", 10),
      )
      return [TextContent(type="text", text=json.dumps(results, indent=2, ensure_ascii=False))]

• tiktok_mcp/server.py:108-119 (registration)

  Tool registration for `tiktok_hashtag` defining the input schema.

  Tool(
      name="tiktok_hashtag",
      description="Explore a TikTok hashtag — popular videos and stats.",
      inputSchema={
          "type": "object",
          "properties": {
              "hashtag": {"type": "string", "description": "Hashtag to explore (with or without #)"},
              "count": {"type": "integer", "description": "Number of videos (default 10)", "default": 10},
          },
          "required": ["hashtag"],
      },
  ),