rgl-mcp

MCP server that wraps the RGL API with natural-language tools. Designed for hosting on fly.io.

What it does

Translates queries like "every player who played IM in S7 of 6s" into the right sequence of API calls:

1. Resolves "6s" → format/region (defaults to NA when not specified).
2. Resolves "S7" → SeasonId by fuzzy-matching cached season list.
3. Resolves "IM" → DivisionId scoped to the region.
4. Fetches the corresponding Group, then its rosters.
5. Optionally bulk-fetches profile data for every unique player.

Tools

Tool	Purpose
find_season	Resolve season phrase → SeasonId
get_season	Reverse lookup: SeasonId → season/region/format metadata (inverse of find_season)
find_region	Resolve region phrase → RegionId
find_division	Resolve division phrase → DivisionId (scoped to a region)
find_team	Substring search on team name/tag
find_player	Substring search on player aliases
get_player	Profile by SteamID
get_team	Team data by TeamId (includes a resolved region block — use region.regionId as the r= value in rgl.gg URLs)
get_match	Match data by MatchId
list_season_divisions	Groups in a season
list_division_teams	Teams in a (season, division)
list_division_players	Every unique player in (season, division), optionally with full profile data
list_formats	All formats (lookup)
list_regions	All regions (lookup)

Local development

npm install
npm run dev

The server reads .env.local for RGL_API_BASE_URL etc. By default it points at the production RGL API.

Deploy

fly launch --name rgl-mcp --copy-config --no-deploy   # first time only
fly deploy

Then point your MCP client at https://rgl-mcp.fly.dev/mcp (Streamable HTTP transport).

Edits aren't live until you fly deploy. The hosted server at https://rgl-mcp.fly.dev/mcp is what MCP clients talk to, so any change to src/ requires a fly deploy to take effect. A connected client also caches the tool list at session start — new or renamed tools only appear in a fresh session after the deploy.

Use with Claude Code

This is an unauthenticated, read-only endpoint over already-public RGL data. Every tool just proxies the public RGL API, so the URL isn't a secret. The server adds no auth of its own, and abuse is naturally bounded by the upstream RGL API's own rate limiting. The open pattern is safe only because nothing here is sensitive — don't bolt private or authenticated data onto this server without first adding auth.

The server is live at https://rgl-mcp.fly.dev/mcp. Add it to Claude Code with the HTTP transport — no local clone or build required, you're connecting straight to the hosted fly instance:

claude mcp add --transport http rgl https://rgl-mcp.fly.dev/mcp

By default this adds the server at local scope (just you, this project). Use --scope user to make it available across all your projects, or --scope project to share it with the repo via a checked-in .mcp.json:

claude mcp add --transport http --scope user rgl https://rgl-mcp.fly.dev/mcp

Verify and inspect the connection:

claude mcp list          # shows rgl as connected
claude mcp get rgl       # shows the URL, transport, and scope

Inside a session, /mcp lists the connected servers and their tools. The tools then show up as mcp__rgl__<tool> (e.g. mcp__rgl__find_season). To remove it later: claude mcp remove rgl.

Configuration

Env var	Default	Meaning
RGL_API_BASE_URL	https://rglgg-api.fly.dev/v0	Base URL of the RGL API
PORT	3000	HTTP listen port
CACHE_REFRESH_MS	3600000	Lookup cache TTL (1h)
DEFAULT_REGION_ID	40	NA Sixes — used when only a format is given