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

# 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: <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](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.