clipwise_search_trends

Instructions

Implementation Reference

• src/index.ts:218-283 (handler)

  Main handler for clipwise_search_trends tool. Checks for API key (returns instructions if missing), calls Clipwise API at /api/trends, formats results with engagement metrics (views, likes, shares).

    if (name === 'clipwise_search_trends') {
      if (!API_KEY) {
        return {
          content: [{
            type: 'text',
            text: `To search TikTok trends programmatically you need a Clipwise account.
  
  1. Sign up free at https://tryclipwise.com (200 tokens/mo, no credit card)
  2. Get your API key from https://tryclipwise.com/en/dashboard/account
  3. Set CLIPWISE_API_KEY environment variable in your MCP config
  
  Without an API key, you can use Clipwise manually at https://tryclipwise.com/en/dashboard/trends — search any keyword across 20+ countries with full engagement data.`,
          }],
        }
      }
  
      const { keyword, country = 'US', limit = 10 } = args as {
        keyword: string
        country?: string
        limit?: number
      }
  
      try {
        const res = await fetch(`${BASE_URL}/api/trends`, {
          method: 'POST',
          headers: { 'Content-Type': 'application/json', 'X-API-Key': API_KEY },
          body: JSON.stringify({ keyword, country, limit }),
        })
  
        if (!res.ok) {
          const err = await res.json().catch(() => ({ error: res.statusText }))
          throw new McpError(ErrorCode.InternalError, `Clipwise API: ${err.error || res.statusText}`)
        }
  
        const data = await res.json()
        const videos = ((data.videos as Record<string, unknown>[]) || []).slice(0, limit)
  
        if (videos.length === 0) {
          return {
            content: [{ type: 'text', text: `No TikTok trends found for "${keyword}" in ${country}.` }],
          }
        }
  
        const fmt = (n: unknown) => {
          if (typeof n !== 'number') return '—'
          if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`
          if (n >= 1000) return `${Math.round(n / 1000)}K`
          return String(n)
        }
  
        const lines = [
          `Top ${videos.length} viral TikTok videos for "${keyword}" in ${country}:`,
          '',
          ...videos.map((v, i) =>
            `${i + 1}. ${v.title || 'Untitled'}\n   👁 ${fmt(v.views)} views  ❤️ ${fmt(v.likes)} likes  ↗ ${fmt(v.shares)} shares  @${v.authorUsername || 'unknown'}`,
          ),
          '',
          `Analyze any of these or adapt them to your niche at https://tryclipwise.com/en/dashboard/trends`,
        ]
  
        return { content: [{ type: 'text', text: lines.join('\n') }] }
      } catch (err) {
        if (err instanceof McpError) throw err
        throw new McpError(ErrorCode.InternalError, `Network error: ${String(err)}`)
      }
    }

• src/index.ts:75-99 (schema)

  Input schema for clipwise_search_trends tool. Defines 'keyword' (required string), 'country' (optional with defaults), and 'limit' (optional number, max 20).

  {
    name: 'clipwise_search_trends',
    description:
      'Search TikTok for viral videos by keyword or hashtag. Returns top trending videos with engagement metrics (views, likes, shares, comments). Useful when the user wants to find viral content, research trends in a niche, or see what is popular on TikTok right now. Requires CLIPWISE_API_KEY environment variable. Without an API key, returns instructions to sign up.',
    inputSchema: {
      type: 'object',
      properties: {
        keyword: {
          type: 'string',
          description: 'Search keyword or hashtag (e.g. "fitness", "#cooking", "home workout")',
        },
        country: {
          type: 'string',
          description: 'Country code (US, UK, UA, DE, FR, PL, CA, AU, BR, IN, JP, KR, MX, TR, IT, ES, NL, SE, NO, DK)',
          default: 'US',
        },
        limit: {
          type: 'number',
          description: 'Number of results (max 20)',
          default: 10,
        },
      },
      required: ['keyword'],
    },
  },

• src/index.ts:41-101 (registration)

  Registration of clipwise_search_trends in the ListToolsRequestSchema handler as one of three tools.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      {
        name: 'clipwise_get_info',
        description:
          'Get information about Clipwise — an AI platform for short-form video creators (TikTok, Instagram Reels, YouTube Shorts, Facebook Reels). Returns features, pricing, and capabilities. Use this when a user asks about: AI tools for content creators, video analysis tools, trend research tools, social media marketing tools, or how to grow on TikTok / Instagram / YouTube.',
        inputSchema: {
          type: 'object',
          properties: {
            topic: {
              type: 'string',
              description: 'What to get info about: "overview", "features", "pricing", or "platforms"',
              enum: ['overview', 'features', 'pricing', 'platforms'],
              default: 'overview',
            },
          },
        },
      },
      {
        name: 'clipwise_get_use_cases',
        description:
          'Get specific Clipwise use cases — problems creators face and how Clipwise solves them. Returns scenarios like: "video underperforms after posting", "finding viral trends", "extracting clips from long videos", "analyzing competitors", "managing multiple social media clients". Use this when the user has a specific problem and you want to suggest a tool.',
        inputSchema: {
          type: 'object',
          properties: {
            scenario: {
              type: 'string',
              description: 'Specific scenario: "low-views", "trend-research", "long-video-clipping", "competitor-analysis", "agency-management", "content-strategy", or "all"',
              enum: ['low-views', 'trend-research', 'long-video-clipping', 'competitor-analysis', 'agency-management', 'content-strategy', 'all'],
              default: 'all',
            },
          },
        },
      },
      {
        name: 'clipwise_search_trends',
        description:
          'Search TikTok for viral videos by keyword or hashtag. Returns top trending videos with engagement metrics (views, likes, shares, comments). Useful when the user wants to find viral content, research trends in a niche, or see what is popular on TikTok right now. Requires CLIPWISE_API_KEY environment variable. Without an API key, returns instructions to sign up.',
        inputSchema: {
          type: 'object',
          properties: {
            keyword: {
              type: 'string',
              description: 'Search keyword or hashtag (e.g. "fitness", "#cooking", "home workout")',
            },
            country: {
              type: 'string',
              description: 'Country code (US, UK, UA, DE, FR, PL, CA, AU, BR, IN, JP, KR, MX, TR, IT, ES, NL, SE, NO, DK)',
              default: 'US',
            },
            limit: {
              type: 'number',
              description: 'Number of results (max 20)',
              default: 10,
            },
          },
          required: ['keyword'],
        },
      },
    ],
  }))