# trendforge-mcp

An [MCP](https://modelcontextprotocol.io) server for **TrendForge** — the YouTube gaming opportunity ranking.

Install it once and Claude Desktop, Cursor, or Codex can answer "what should I record?" by querying TrendForge's live ranking directly, without you leaving the chat.

## What it exposes

Three read-only tools:

| Tool | What it does |
|---|---|
| `list_opportunities` | Top games right now ranked by opportunity score (Demand / Supply / Timing). |
| `get_game` | One game's full breakdown + AI video ideas + related games. |
| `check_topic` | Live YouTube shelf check on any game/topic (heavier — use for serious ideas). |

Scores: `opportunity = 0.4·Demand + 0.35·Supply + 0.25·Timing`, each 0–100, higher is better. See the [full methodology](https://trendforgeapp.com/how-we-score).

## Install

### Claude Desktop

Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "trendforge": {
      "command": "npx",
      "args": ["-y", "trendforge-mcp"]
    }
  }
}
```

Restart Claude Desktop. You'll see `trendforge` in the tools list.

### Cursor

Add to `.cursor/mcp.json` (project) or global MCP settings:

```json
{
  "mcpServers": {
    "trendforge": {
      "command": "npx",
      "args": ["-y", "trendforge-mcp"]
    }
  }
}
```

### Codex (`codex` CLI)

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.trendforge]
command = "npx"
args = ["-y", "trendforge-mcp"]
```

## Configuration

| Env var | Default | Purpose |
|---|---|---|
| `TRENDFORGE_HOST` | `https://trendforgeapp.com` | Override the TrendForge host (e.g. for a staging build). |

Example with a custom host:

```json
{
  "mcpServers": {
    "trendforge": {
      "command": "npx",
      "args": ["-y", "trendforge-mcp"],
      "env": { "TRENDFORGE_HOST": "https://staging.example" }
    }
  }
}
```

## Try it

Once connected, ask your assistant things like:

- "What are the top 10 YouTube gaming opportunities right now for a small channel?"
- "Give me video ideas for Palworld."
- "Check whether a Hades 2 beginner guide is worth making — I have under 1K subs."

## Local development

```bash
npm install
npm run build
node bin/trendforge-mcp.js   # speaks MCP over stdio
```

## Notes

- All data is read-only and computed from public Steam, YouTube Data API, and Google Trends signals.
- `check_topic` hits the YouTube API and is rate-limited server-side, same as the [free web checker](https://trendforgeapp.com/free-tools/game-checker).
- Not affiliated with Valve, Google, or YouTube.