<p align="center"> <img src="assets/icon.png" alt="ShortsMonkey" width="112" height="112" /> </p>

ShortsMonkey MCP

English | 简体中文

ShortsMonkey MCP is a read-only remote Model Context Protocol server for YouTube outlier discovery, viral Shorts rankings, and single-video performance analysis.

It gives MCP-compatible AI assistants access to stored ShortsMonkey data so creators, agencies, researchers, and content teams can find low-subscriber videos with unusually high views and turn those examples into research-backed content decisions.

Connect to the hosted server

Remote Streamable HTTP endpoint:

https://mcp.shortsmonkey.com/mcp

Create a smcp_live_... token at ShortsMonkey MCP Access, then configure a client that supports remote Streamable HTTP and custom headers.

Cursor configuration:

{
  "mcpServers": {
    "shortsmonkey-mcp": {
      "url": "https://mcp.shortsmonkey.com/mcp",
      "headers": {
        "Authorization": "Bearer smcp_live_your_token_here"
      }
    }
  }
}

Do not commit the token or place it in a shared configuration. See the complete user guide for account, quota, and token-rotation instructions.

Tools

get_hot_today

Returns the current ShortsMonkey hot-today YouTube Shorts leaderboard from stored database snapshots.

Input	Description
region	Optional region code such as US, JP, BR, or IN
tier	S, A, B, C, or all; defaults to all
limit	1-50 results; defaults to 20

Example: Find today's 10 hottest YouTube Shorts in the US.

search_outlier_videos

Searches stored outlier snapshots by keyword, niche, region, format, views, subscribers, and views-to-subscribers ratio.

Input	Description
keyword	Optional title, channel, tag, or source-keyword search
niche	Optional niche or category text
videoType	shorts, long, or all; defaults to all
region	Optional region code
maxChannelSubscribers	Maximum channel subscriber count
minViews	Minimum video view count
minVsRatio	Minimum views/subscribers ratio; defaults to 10
timeWindow	24h, 3d, 7d, or 30d; defaults to 7d
limit	1-50 results; defaults to 20

Example: Find long-form AI videos from the last 7 days with fewer than 50,000 subscribers and a V/S ratio above 20.

analyze_video_url

Analyzes one YouTube watch, Shorts, embed, or youtu.be URL using a stored ShortsMonkey performance snapshot.

Input	Description
url	Required YouTube video URL

Example: Analyze this YouTube video and explain whether it is an outlier: <URL>

All three tools declare readOnlyHint: true, destructiveHint: false, idempotentHint: true, and openWorldHint: false.

Returned data

Depending on the tool, responses can include:

• video and channel URLs
• channel subscriber count and video views
• views-to-subscribers ratio and viral score
• Shorts or long-form classification
• niche, region, publish time, and snapshot time
• a concise numeric explanation of why the result is an outlier

Values come from stored ShortsMonkey snapshots and may differ from the current numbers displayed by YouTube.

Quotas and authentication

• Authentication uses Authorization: Bearer smcp_live_....
• Trial accounts receive five MCP tool calls during the trial.
• Paid accounts receive 200 calls per day, shared with ShortsMonkey website searches.
• Each account can keep up to three active tokens.
• Default HTTP protection limits are 90 requests per token per minute and 180 requests per IP per minute.

Tokens can be created, rotated, and revoked from MCP Access.

Health checks

GET https://mcp.shortsmonkey.com/health
GET https://mcp.shortsmonkey.com/ping
GET https://mcp.shortsmonkey.com/.well-known/mcp/server-card.json

/ping is an alias provided for Glama hosting probes. A browser GET to /mcp returns 405 Method Not Allowed by design because MCP protocol requests use POST. The public server card exposes only static MCP metadata so registries can discover the three tools without receiving a user token; tool calls still require authentication.

Architecture

MCP client
  -> ShortsMonkey MCP gateway (this repository)
  -> private ShortsMonkey application API
  -> stored YouTube research snapshots

The gateway validates account tokens through the private ShortsMonkey application, applies rate limits, registers MCP tools, and converts internal JSON responses into MCP text and structured content.

The repository intentionally does not contain the ShortsMonkey database, account system, billing logic, internal service credentials, or proprietary data-query implementation.

Development

Requirements:

• Node.js 20 or newer
• npm
• authorized access to the private ShortsMonkey internal API

npm ci
cp .env.example .env
npm run dev

The local endpoint defaults to http://localhost:3001/mcp. Health checks are available at /health and /ping.

Run all checks:

npm run check

Required server environment

Variable	Purpose
SHORTSMONKEY_INTERNAL_API_BASE_URL	Base URL of the ShortsMonkey application
SHORTSMONKEY_INTERNAL_SERVICE_TOKEN	Private server-to-server credential
MCP_ALLOWED_ORIGINS	Comma-separated browser origins allowed in production
MCP_IP_RATE_LIMIT_PER_MINUTE	Per-instance source-IP request limit
MCP_TOKEN_RATE_LIMIT_PER_MINUTE	Per-instance authenticated-principal request limit

MCP_ALLOW_LEGACY_KEYS is disabled by default and must remain disabled in normal production deployments.

Docker

docker build -t shortsmonkey-mcp .
docker run --rm --env-file .env -p 3001:3001 shortsmonkey-mcp

The image runs as the unprivileged node user and includes a /ping health check.

Glama

This repository includes a root glama.json, a production Dockerfile, static tool schemas, annotations, tests, and a complete Glama submission checklist.

Repository URL for submission:

https://github.com/cuilinhao/youtube-mcp

Security

Read SECURITY.md and report vulnerabilities privately to support@shortsmonkey.com.

Source-use notice

This repository currently has no open-source license grant. The source is published for transparency and review. Contact support@shortsmonkey.com before reuse or redistribution outside contributions to this repository.