TopYappers MCP Server

TopYappers MCP Server

A Model Context Protocol (MCP) server that gives AI agents access to the TopYappers API for discovering viral content, trending songs, influencers, and outreach agent email history.

Available Tools

| Tool | Description | Cost | |------|-------------|------| | search_viral_content | Find viral TikTok posts by category, country, views, virality score, dates, music, hooks | 1 credit/result | | search_creators | Search influencers across TikTok, Instagram, YouTube, LinkedIn, and X/Twitter with 20+ filters | Free | | get_creator_profiles | Fetch full creator profiles by IDs | 1 credit/creator | | list_agent_projects | List outreach agent projects and campaign context | Free | | list_contacted_creators | List creators contacted via agent email, with reply/thread context | Free | | list_agent_messages | List sent and received outreach emails by creator, project, thread, or direction | Free | | search_videos | Search videos by engagement, hashtags, text | 1 credit/video | | get_song_rankings | Country or global song chart rankings | 10 credits | | get_new_song_entries | Newly charting songs for a country | 10 credits | | search_songs | Search songs by title/artist | 10 credits | | get_song_history | Song chart performance over time | 10 credits | | compare_song_rankings | Compare charts between two weeks | 10 credits | | get_song_countries | List available countries for song data | 10 credits | | get_song_weeks | List available weeks for a country | 10 credits |

Getting Started

1. Get a TopYappers API key at topyappers.com/profile
2. Add the MCP server to your client (see below)

Setup

Claude Web/Desktop Custom Connector (OAuth)

Use these values when adding TopYappers as a hosted custom connector:

| Field | Value | |------|-------| | Connector URL | https://mcp.topyappers.com/mcp | | Auth type | OAuth | | Client ID | myapp-claude | | Client Secret | YOUR_TOPYAPPERS_API_KEY |

Claude will ask you to connect; click Connect. The OAuth flow is a proxy shim for Claude's connector UI: your TopYappers API key is used as the OAuth client secret, and the server returns it as the MCP bearer access token.

Claude Code (CLI)

claude mcp add --transport http topyappers https://mcp.topyappers.com/mcp \
  --header "Authorization: Bearer YOUR_TOPYAPPERS_API_KEY"

Or add to .mcp.json in your project root:

{
  "mcpServers": {
    "topyappers": {
      "type": "http",
      "url": "https://mcp.topyappers.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOPYAPPERS_API_KEY"
      }
    }
  }
}

Cursor

Add to your MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "topyappers": {
      "url": "https://mcp.topyappers.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOPYAPPERS_API_KEY"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "topyappers": {
      "url": "https://mcp.topyappers.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOPYAPPERS_API_KEY"
      }
    }
  }
}

Authentication

For non-Claude MCP clients, use the MCP endpoint https://mcp.topyappers.com/mcp and pass your TopYappers API key as a Bearer token in the Authorization header. The server also accepts X-API-Key, X-MyApp-API-Key, and Api-Key headers.

The root URL https://mcp.topyappers.com is a clean human/info endpoint. Browser GET /mcp intentionally returns 405 Method Not Allowed; MCP clients should POST JSON-RPC messages to /mcp.

Documentation

Detailed docs for each API domain:

• Overview — how it works, auth, credits
• Creators & Influencers — search workflow, parameters, power filters
• Agent Outreach — projects, contacted creators, sent messages, replies
• Viral Content — filters, virality score, use cases
• Videos — search, sort, engagement filters
• Trending Songs — rankings, new entries, history, comparisons
• Reference — all enums, countries, categories, languages

Example Workflows

Find viral fitness content from the US

1. Call search_viral_content with categories: ["Fitness"], countries: ["United States"], viralityScoreMin: 0.5
2. Get back viral videos with engagement metrics and creator info

Discover fashion influencers on Instagram

1. Call search_creators with source: "instagram", mainCategory: "Fashion", followersMin: 50000 (free)
2. Call get_creator_profiles with the returned userIds (1 credit each)
3. Get full profiles with email, bio, engagement rate, etc.

Find trending songs in the UK

1. Call get_song_rankings with country: "GB"
2. Get the latest chart with song titles, artists, ranks, and movement
3. Call get_song_history for deeper analysis of a specific song

Draft a reply to a creator who emailed back

1. Call list_contacted_creators with creatorEmail: "creator@example.com"
2. Call list_agent_messages with the same creatorEmail and direction: "all"
3. Use the original pitch, follow-ups, inbound reply, and project details to draft a customized response

Rate Limits

• 60 requests per minute per API key
• HTTP 429 responses include retryAfter indicating seconds to wait

Links

• TopYappers Platform
• API Documentation
• Get an API Key