Virlo Agent Plugin

Give your AI agent a social media brain. Find what's trending on TikTok, YouTube Shorts, and Instagram Reels, see why a video went viral, look up any creator, and catch trending sounds and hashtags before they peak, all from Claude, Cursor, Grok, Codex, or any MCP client.

Works with: Claude Code, Claude Desktop, claude.ai, Cursor, Grok Build, VS Code, Windsurf, OpenAI Codex, and any MCP-compatible agent.

Built on the Virlo API. Virlo is a short-form social intelligence platform covering TikTok, YouTube Shorts, Instagram Reels, and Meta Ads across every niche.

What your agent can do

• Spot trends early: emerging trends, a daily trend digest, and the top viral videos of the last 48 hours
• Explain virality: break down why a specific video popped (hook, format, sound, timing)
• Research any niche: run a research agent that finds the top videos, creator outliers, and content patterns for a topic
• Monitor a niche every week: recurring research agents that surface rising sounds, hashtags, and creators
• Look up creators: profile, outlier videos, audience demographics and geography, posting cadence
• Find trending sounds and hashtags: breakout audio, sound usage history, hashtag growth
• Steal hooks that work: trending hooks and a searchable hook library
• Track over time: daily tracking of creators and videos with signal reports

Install

Skill (Claude Code, Cursor, Codex, Windsurf, and other agents)

npx skills add Virlo-AI/Virlo-Agent-Plugin

Two skills ship in this repo:

| skill | what it does | |---|---| | virlo | Routes each question to the right Virlo tool, handles async research jobs, keeps credit spend visible | | short-form-trend-research | Content strategist: turns live trend data into a weekly plan of trends, sounds, hooks, and video ideas |

Install just one with --skill:

npx skills add Virlo-AI/Virlo-Agent-Plugin --skill short-form-trend-research

The skills need the Virlo MCP server connected. See MCP server.

Claude Code plugin

/plugin marketplace add Virlo-AI/Virlo-Agent-Plugin
/plugin install virlo@virlo

The plugin connects the MCP server for you. Sign in to Virlo when prompted. No API key needed.

Grok Build plugin

/plugin marketplace add xai-org/plugin-marketplace
/plugin install virlo@xai-official

The plugin connects the MCP server for you. Sign in to Virlo when prompted. No API key needed.

<details> <summary>Cursor and manual install</summary>

Cursor: install Virlo from the Cursor plugin marketplace, then set VIRLO_API_KEY in your environment (see Setup).

Manual: clone this repo and copy skills/virlo/ (and optionally skills/short-form-trend-research/) into your project's .claude/skills/ or .cursor/skills/ folder.

Local development:

claude --plugin-dir ./Virlo-Agent-Plugin

</details>

Agent Plugins standard

This repo is a portable Agent Plugin (spec 1.0.0). Root plugin.json + mcp.json + skills/ let any compatible client load the Virlo skills and connect to the hosted MCP server from this one package. Client-specific manifests live side by side:

| file | client | |---|---| | plugin.json, mcp.json | Agent Plugins 1.0.0 (Cursor, VS Code, and others as they adopt it) | | .claude-plugin/, .mcp.json | Claude Code (OAuth, no key) | | .cursor-plugin/plugin.json | Cursor marketplace | | .grok-plugin/plugin.json, .mcp.json | Grok Build (xAI plugin marketplace) | | server.json | MCP Registry | | rules/virlo-api-usage.mdc | Cursor always-apply rule | | commands/ | Slash commands (Claude Code, Cursor) |

Setup

Claude Code, Claude Desktop, claude.ai, Grok Build: nothing to set up. Sign in to Virlo when the client asks. A dedicated API key is created for you.

Cursor, VS Code, Windsurf, Codex, and other clients:

1. Create an API key at dev.virlo.ai/dashboard/api-keys. It starts with virlo_tkn_.

2. Set it in your environment:

   export VIRLO_API_KEY=virlo_tkn_xxxxx
   

   Add it to ~/.zshrc or ~/.bashrc to keep it across sessions. mcp.json reads it as ${env:VIRLO_API_KEY} (Cursor syntax; check your client's equivalent).

3. Restart your client.

Start using it

Ask your agent things like:

• "What's trending on TikTok in the fitness niche this week?"
• "Why did this video go viral?" (paste a TikTok, Shorts, or Reels link)
• "Look up @creator on YouTube and show me their outlier videos."
• "Which sounds are breaking out right now?"
• "Give me 10 hooks that work for SaaS founders on short-form."
• "Set up a weekly monitor for skincare content on TikTok and Instagram."
• "Plan my next week of Reels for a home-cooking account."

Slash commands

| command | what it does | |---|---| | /trend-scout | Trend report across TikTok, Shorts, and Reels: emerging trends, viral videos, breakout sounds, rising hashtags | | /creator-deep-dive | Full analysis of one creator: outliers, themes, cadence, engagement | | /niche-analysis | Research agent + top creators + recurring monitor for a niche | | /genre-monitor | Recurring TikTok genre or scene monitor with sound, hashtag, and creator signals |

MCP server

Virlo runs a hosted, remote MCP server. Any MCP client can connect directly, with no install.

• Endpoint: https://dev.virlo.ai/api/mcp/mcp (streamable HTTP)
• Auth: OAuth 2.0 with dynamic client registration (Claude clients), or Authorization: Bearer virlo_tkn_...

Claude Code (no plugin):

claude mcp add --transport http virlo https://dev.virlo.ai/api/mcp/mcp

Claude Desktop / claude.ai: add a custom connector with the endpoint URL above and sign in. Leave the OAuth client ID and secret blank.

Cursor / VS Code / other HTTP clients:

{
  "mcpServers": {
    "virlo": {
      "url": "https://dev.virlo.ai/api/mcp/mcp",
      "headers": { "Authorization": "Bearer virlo_tkn_your_key_here" }
    }
  }
}

Clients without remote MCP support (via mcp-remote):

{
  "mcpServers": {
    "virlo": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://dev.virlo.ai/api/mcp/mcp", "--header", "Authorization: Bearer virlo_tkn_your_key_here"]
    }
  }
}

Tools

65 tools. The current list and pricing live at dev.virlo.ai/docs/mcp.

| area | tools | |---|---| | Pop culture & News (topics by region) | get_emerging_trends, get_trends_digest, get_trends | | Trending videos | get_trending_videos | | Content Trends (video formats creators are copying right now) | get_content_trends, get_content_trend | | Research agents | suggest_keywords, search_keywords, get_keyword_search_results, list_keyword_searches | | Niche monitors | create_niche_monitor, get_niche_monitor_data, list_niche_monitors, get_niche_monitor_proposals, set_niche_monitor_autonomy | | Creators | lookup_creator, batch_lookup_creators, get_creator_audience_demographics, get_creator_audience_geography, get_posting_cadence | | Videos | analyze_video, track_video, get_tracking_report | | Sounds | get_breakout_sounds, get_trending_sounds, lookup_sound, search_sounds, get_sound_usage_history | | Hashtags | search_hashtags, lookup_hashtag, get_hashtag_performance | | Hooks | get_trending_hooks, search_hooks, get_hook_library, get_hook_types | | Account | get_credit_balance, check_job_status |

Costs

Most research tools bill per call. Research agents cost $0.50 per run (+$1.00 with Data Intelligence). Recurring monitors bill on every run. Re-reading results you already have is free. The virlo skill checks your balance and asks before it spends. Full pricing: dev.virlo.ai/docs/mcp.

Troubleshooting

Virlo tools do not show up

The MCP server is not connected. Claude clients: sign in again. Other clients: confirm VIRLO_API_KEY is set in the environment your client starts from, then restart the client.

401 or 403 errors

The key is wrong or revoked. Create a new one at dev.virlo.ai/dashboard/api-keys.

A research run returns no videos

This is almost always an intent or keyword problem, not an outage. Write a sharper one-sentence intent and run suggest_keywords again.

Results have empty fields

The job is not finished. Wait for finalized: true. Research agents usually finish collecting in about 8 minutes (9 in 10 within 20).

Network & credentials

The only endpoint this plugin talks to is Virlo's MCP server, https://dev.virlo.ai/api/mcp/mcp, authenticated with OAuth or the VIRLO_API_KEY you provide (sent only in the Authorization header of that request). No other network calls, no telemetry, no local commands, no file writes. The skills read public social data only. They never post to or change your social accounts.

Links

• Virlo
• MCP setup and tool reference
• API keys

License

MIT