# ShortsMonkey MCP English | [简体中文](README.zh-CN.md) 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: ```text https://mcp.shortsmonkey.com/mcp ``` Create a `smcp_live_...` token at [ShortsMonkey MCP Access](https://www.shortsmonkey.com/en/mcp-access), then configure a client that supports remote Streamable HTTP and custom headers. Cursor configuration: ```json { "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](https://www.shortsmonkey.com/en/youtube-mcp) 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: ` 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](https://www.shortsmonkey.com/en/mcp-access). ## Health checks ```text 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 ```text 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 ```bash 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: ```bash 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 ```bash 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`](glama.json), a production Dockerfile, static tool schemas, annotations, tests, and a complete [Glama submission checklist](docs/GLAMA_SUBMISSION.md). Repository URL for submission: ```text https://github.com/cuilinhao/youtube-mcp ``` ## Security Read [SECURITY.md](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.