Viral Finder MCP Server

An MCP (Model Context Protocol) server that lets AI assistants analyze videos for viral potential using Viral Finder's AI engine.

When installed, your AI assistant (Claude, Cursor, etc.) gains the ability to:

• Analyze any video (YouTube, TikTok, Instagram) and get a viral score, verdict, strengths, and weaknesses
• Evaluate video hooks for engagement potential with psychology-based scoring
• Review video scripts before recording, with scores for hook, structure, and CTA
• Compare videos side by side with ranked results and a declared winner
• Batch analyze up to 10 videos in a single call, ranked by viral score
• Extract metadata from any video URL instantly (free, no tokens needed)

Installation

Claude Desktop

Add this to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "viral-finder": {
      "command": "npx",
      "args": ["-y", "viral-finder-mcp"],
      "env": {
        "VIRAL_FINDER_API_KEY": "vf_your_key_here"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json in your project root, or global settings):

{
  "mcpServers": {
    "viral-finder": {
      "command": "npx",
      "args": ["-y", "viral-finder-mcp"],
      "env": {
        "VIRAL_FINDER_API_KEY": "vf_your_key_here"
      }
    }
  }
}

Claude Code

Add to your Claude Code settings:

claude mcp add viral-finder -- npx -y viral-finder-mcp

Then set the environment variable VIRAL_FINDER_API_KEY in your shell profile.

Getting an API Key

1. Sign up or log in at viralfinder.ai
2. Go to Settings > API Keys
3. Create a new key (it will start with vf_)
4. Add the key to your MCP configuration as shown above

The API key is required for analyze_video, analyze_batch, and compare_videos. The analyze_hook, review_script, and extract_metadata tools are free and work without a key.

Available Tools

All tools support a format parameter with three options:

| Format | Description | |--------|-------------| | "both" | Markdown + JSON block appended (default) | | "markdown" | Human-readable markdown only | | "json" | Structured JSON only (best for programmatic use) |

analyze_video

Analyze a video URL for viral potential. Returns a comprehensive report with scores, verdict, strengths, and weaknesses.

Auth: Requires VIRAL_FINDER_API_KEY

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | url | string | Yes | Video URL (YouTube, TikTok, or Instagram) | | model | "flash" or "pro" | No | AI model. Flash is faster/cheaper (10 tokens), Pro is more detailed (40 tokens). Default: flash. | | format | "json", "markdown", "both" | No | Output format. Default: both. |

Example prompts:

• "Analyze this YouTube video for viral potential: https://youtube.com/watch?v=..."
• "Use the pro model to analyze this TikTok: https://tiktok.com/@user/video/..."

Structured JSON output:

{
  "score": 85,
  "verdict": "This video has strong viral characteristics...",
  "summary": "A well-crafted short-form video...",
  "strengths": ["Excellent hook", "High emotional engagement"],
  "weaknesses": ["Title could be more clickable"],
  "suggestions": [],
  "metadata": {
    "model": "flash",
    "tokens_consumed": 10,
    "analyzed_at": "2026-04-01T12:00:00Z",
    "url": "https://youtube.com/watch?v=...",
    "id": "abc123"
  },
  "scores": {
    "hook": 9,
    "video_quality": 8,
    "shareability": 8
  }
}

analyze_hook

Evaluate a video hook/opening line for engagement potential. Returns scoring, psychology analysis, platform-specific scores, and rewrite suggestions.

Auth: Free (no API key needed), rate-limited to 1/day per IP

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | text | string | Yes | The hook text to analyze (5-500 characters) | | format | "json", "markdown", "both" | No | Output format. Default: both. |

Example prompts:

• "Analyze this hook: 'Nobody talks about this hack that got me 1M views'"
• "Rate this video opening: 'What if I told you everything you know about productivity is wrong?'"

review_script

Review a short-form video script before recording. Returns scores for hook, structure, and CTA, plus the top issue and one actionable fix.

Auth: Free (no API key needed), rate-limited to 1/day per IP

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | text | string | Yes | The full script text (20-3000 characters) | | format | "json", "markdown", "both" | No | Output format. Default: both. |

Example prompts:

• "Review this script for my YouTube Short: [paste script]"
• "Check if this TikTok script will go viral: [paste script]"

extract_metadata

Extract metadata from a video URL without running full analysis. Returns title, platform, creator, and thumbnail. Fast, free, and does not consume analysis tokens.

Auth: Free (no API key needed, no rate limit)

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | url | string | Yes | Video URL (YouTube, TikTok, or Instagram) | | format | "json", "markdown", "both" | No | Output format. Default: both. |

Uses platform oEmbed APIs (YouTube, TikTok) to retrieve metadata. Instagram metadata is limited since Instagram oEmbed requires authentication.

Example prompts:

• "Get the metadata for this video: https://youtube.com/watch?v=..."
• "What's the title and creator of this TikTok?"

Structured JSON output:

{
  "platform": "youtube",
  "title": "10 Tips for Going Viral",
  "creator": "CreatorName",
  "thumbnail_url": "https://i.ytimg.com/vi/.../hqdefault.jpg",
  "url": "https://youtube.com/watch?v=..."
}

analyze_batch

Analyze multiple video URLs in a single call. Returns results for each video, ranked by viral score. Useful for comparing content, ranking options, or bulk analysis.

Auth: Requires VIRAL_FINDER_API_KEY

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | urls | string[] | Yes | Array of 2-10 video URLs to analyze | | model | "flash" or "pro" | No | AI model for all videos. Default: flash. | | format | "json", "markdown", "both" | No | Output format. Default: both. |

Videos are analyzed sequentially with rate-limit-friendly pacing. Failed analyses are included in results with error status. Results are sorted by score (highest first).

Example prompts:

• "Analyze all 5 of my latest videos: [url1, url2, url3, url4, url5]"
• "Rank these 3 TikToks by viral potential: [url1, url2, url3]"

Token cost: 10 tokens per video (flash) or 40 tokens per video (pro). Example: 5 videos with flash = 50 tokens.

compare_videos

Compare 2-5 videos side by side. Returns a ranked comparison with a declared winner, score differences, and specific advantages/disadvantages of each video.

Auth: Requires VIRAL_FINDER_API_KEY

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | urls | string[] | Yes | Array of 2-5 video URLs to compare | | model | "flash" or "pro" | No | AI model for all videos. Default: flash. | | format | "json", "markdown", "both" | No | Output format. Default: both. |

The comparison determines: overall winner with reason, best hook, best shareability, biggest weakness across all videos.

Example prompts:

• "Compare these two videos and tell me which one is better: [url1] vs [url2]"
• "Which of these 3 videos has the most viral potential? [url1, url2, url3]"

Structured JSON output:

{
  "ranking": [
    { "position": 1, "url": "...", "score": 85, "verdict": "..." },
    { "position": 2, "url": "...", "score": 72, "verdict": "..." }
  ],
  "winner": {
    "url": "...",
    "score": 85,
    "reason": "Scored 13 points higher than the runner-up with excellent hook"
  },
  "comparison": {
    "best_hook": { "url": "...", "score": 9 },
    "best_shareability": { "url": "...", "score": 8 },
    "biggest_weakness": { "url": "...", "issue": "Weak CTA at the end" }
  },
  "detailed_results": [...]
}

Output Format Examples

All tools support format: "json" | "markdown" | "both" (default: "both").

format: "json" — structured data only

{
  "schema_version": "2.0.0",
  "score": 82,
  "verdict": "Strong viral potential with an excellent hook and high emotional engagement.",
  "summary": "This gaming video effectively uses pattern interrupts and curiosity gaps...",
  "strengths": [
    "Hook grabs attention in the first 2 seconds",
    "High emotional engagement throughout",
    "Strong call to action that encourages sharing"
  ],
  "weaknesses": [
    "Title could be more clickable",
    "Missing trending hashtags for discoverability"
  ],
  "suggestions": [],
  "metadata": {
    "model": "flash",
    "tokens_consumed": 10,
    "analyzed_at": "2026-04-01T12:34:56Z",
    "url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "scores": {
    "hook": 9,
    "video_quality": 7,
    "shareability": 8
  }
}

format: "markdown" — human-readable only

## Video Analysis Result

**Score:** 82/100 --- HIGH VIRAL POTENTIAL

**Verdict:** Strong viral potential with an excellent hook and high emotional engagement.

### Scores Breakdown
- **Hook:** 9/10
- **Video Quality:** 7/10
- **Shareability:** 8/10

### Strengths
- Hook grabs attention in the first 2 seconds
- High emotional engagement throughout

### Weaknesses
- Title could be more clickable
- Missing trending hashtags

format: "both" (default) — markdown + JSON block

Returns the markdown above, followed by a horizontal rule and a fenced JSON code block containing the structured data. This is the default — agents can parse the JSON block programmatically while humans read the markdown.

Rate Limits & Usage Policy

| Tool | Auth | Rate Limit | Token Cost | |------|------|-----------|------------| | analyze_video | API key | Per plan | 10 (flash) / 40 (pro) | | analyze_hook | Free | 1/day per IP | 0 | | review_script | Free | 1/day per IP | 0 | | extract_metadata | Free | No limit | 0 | | analyze_batch | API key | Per plan | 10-40 per video | | compare_videos | API key | Per plan | 10-40 per video |

Batch & Compare considerations:

• analyze_batch with 10 videos on flash = 100 tokens per call
• compare_videos with 5 videos on pro = 200 tokens per call
• Videos are analyzed sequentially (~5-10s per video) to respect API rate limits
• If one video fails, the rest still complete — partial results are returned

Plan token budgets:

• Free: 700 tokens/month
• Creator ($9/mo): 7,000 tokens/month
• Agency ($19/mo): 10,000 tokens/month

Schema Versioning

All structured JSON responses include a schema_version field (e.g., "2.0.0"). This follows semver — breaking changes to the response schema will bump the major version. Your agent code can check this field to handle different response formats gracefully.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | VIRAL_FINDER_API_KEY | For analyze_video, analyze_batch, compare_videos | Your API key from viralfinder.ai (starts with vf_) | | VIRAL_FINDER_API_URL | No | Custom API base URL (default: https://viralfinder.ai) |

Reliability

All API calls include:

• 30-second timeout via AbortController
• 1 automatic retry on server errors (5xx) and network failures with a 2-second delay
• No retry on client errors (4xx) such as auth failures, rate limits, or bad requests

Error Messages

Errors are designed to be human-readable and actionable:

| Situation | Example message | |-----------|-----------------| | Missing API key | "This tool requires a VIRAL_FINDER_API_KEY. Get yours at https://viralfinder.ai/en/settings" | | Invalid API key | "Your API key appears to be invalid. Keys start with 'vf_'." | | Rate limited | "Rate limit reached. Free tools allow 1 use per day." | | No tokens | "Not enough tokens. Upgrade at https://viralfinder.ai/en/billing" | | Bad URL | "URL not recognized as YouTube, TikTok, or Instagram." | | Network error | "Could not reach Viral Finder API. Check your internet connection." | | Timeout | "Request timed out after 30 seconds. Please try again." |

Development

# Clone and install
cd mcp-server
npm install

# Run in development mode
VIRAL_FINDER_API_KEY=vf_xxx npm run dev

# Build for production
npm run build
npm start

Troubleshooting

"VIRAL_FINDER_API_KEY environment variable is not set" Make sure you added the env block with your API key in the MCP configuration. The key must start with vf_.

"Rate limited" The free tools (analyze_hook, review_script) are limited to 1 use per day without an account. The analyze_video tool has rate limits based on your plan. Wait a moment and try again.

"Insufficient tokens" Your Viral Finder account has run out of tokens. Check your balance and upgrade at viralfinder.ai/billing.

Tool not appearing in Claude Desktop

1. Make sure you saved the config file and restarted Claude Desktop
2. Check that npx is available in your PATH
3. Look at Claude Desktop's MCP logs for errors

License

MIT