Sports Hub MCP Server

A unified MCP server that aggregates 42 sports API providers into a single service. 410 tools covering scores, stats, odds, esports, college sports, chess, motorsport, boxing, AFL, and more across 70+ sports.

Each provider works independently. You only need API keys for the providers you use. Missing keys don't block startup — tools return an error when called without their key.

Works with:

Demo

mcp-sports-hub demo

NBA scores, Premier League odds, Tennis H2H — all from a single MCP server.

Compatibility

Platforms

OS	Status
macOS	Supported
Linux	Supported
Windows	Supported

MCP Clients

Client	Status	Notes
Claude Desktop	Supported	Anthropic's desktop app
Claude Code (CLI)	Supported	`claude mcp add`
Cursor	Supported	Built-in MCP
Windsurf (Codeium)	Supported	Built-in MCP
Continue.dev	Supported	Open-source AI assistant
Cline	Supported	VS Code extension
Zed	Supported	Built-in MCP
ChatGPT Desktop	Supported	OpenAI desktop app
Gemini CLI	Supported	Google CLI
Any MCP client	Supported	Stdio + HTTP/SSE transport

Uses the stdio transport from the MCP SDK. Works with any LLM (Claude, GPT, Gemini, Llama, Mistral, etc.).

Requirements: Node.js 18+, npm.

Providers (32)

Works instantly — no API key, no signup (19 providers, ~165 tools)

These providers work out of the box. Just build and run.

Prefix	Provider	Coverage	Tools	Notes
`espn_`	ESPN	20+ sports	10	Unofficial — can break
`nhl_`	NHL Web API	NHL	13	Undocumented but stable
`mlb_`	MLB Stats API	MLB/MiLB	13	Official, undocumented
`f1_`	Jolpica F1	Formula 1 (1950+)	13	Community-maintained
`openf1_`	OpenF1	F1 live telemetry	12	Live race weekends only
`openliga_`	OpenLigaDB	German football	10	Bundesliga focus
`sportsdb_`	TheSportsDB	40+ sports	13	Test key auto, watermarks
`ncaa_`	NCAA API	College sports	8	5 req/s rate limit
`sportsrc_`	SportSRC	Football, basketball, MMA + streams	7	V1 free, V2 needs paid key
`lichess_`	Lichess	Chess (users, top players, broadcasts, daily puzzle)	7	~20 req/sec/IP
`chesscom_`	Chess.com	Chess (profiles, stats, clubs, leaderboards)	7	Throttles on parallel calls
`squiggle_`	Squiggle	AFL (Australian Football League)	6	Honest UA required
`motogp_`	MotoGP	MotoGP/Moto2/Moto3/MotoE	7	Unofficial — can break
`formulae_`	Formula E	Formula E	7	Unofficial — can break
`nascar_`	NASCAR	NASCAR Cup/Xfinity/Truck	3	Unofficial CDN feeds
`opendota_`	OpenDota	Dota 2 analytics	11	60 req/min, 50k/mo
`sleeper_`	Sleeper	NFL fantasy	10	~1000 req/min
`euroleague_`	EuroLeague	EuroLeague + EuroCup basketball	6	Keyless feeds
`footballdata_uk_`	Football-Data.co.uk	Historical football results + odds	2	CSV, 25+ leagues

Tip: Use SPORTS_HUB_PROVIDERS=free to load only these 19 providers (~165 tools).

Free tier with API key — signup required, no credit card (23 providers, ~245 tools)

Registration takes 1-2 minutes. All keys are free.

Prefix	Provider	Coverage	Tools	Free Limit	Get Key
`pandascore_`	PandaScore	Esports (13 titles)	14	1000 req/hr	Sign up
`apifootball_`	API-Football	Soccer (960+ leagues)	15	100 req/day	Sign up
`apisports_`	API-Sports	9 sports	10	100 req/day/sport	Sign up
`apitennis_`	API-Tennis	Tennis (ATP/WTA/ITF)	12	100 req/day	Sign up
`bdl_`	BallDontLie	NBA/NFL/MLB/NHL	10	Basic tier	Sign up
`cricket_`	CricketData	Cricket	10	100 req/day	Sign up
`entitycricket_`	Entity Sport	Cricket (250+ comps)	12	Free plan	Sign up
`footballdata_`	football-data.org	Soccer (12 leagues)	11	10 req/min	Sign up
`sportmonks_`	Sportmonks	Soccer	12	3000 req/hr	Sign up
`sportsdata_`	SportsDataIO	9 sports	12	1000 req/mo	Sign up
`odds_`	The Odds API	70+ sports odds	9	500 req/mo	Sign up
`oddsio_`	Odds-API.io	34 sports odds	10	Free account	Sign up
`sgo_`	Sports Game Odds	55+ leagues odds	10	Trial	Sign up
`lumify_`	Lumify	Odds, splits + AI bet analysis (8 sports)	14	Free trial key	Sign up
`mma_`	Fighting Tomatoes	MMA	8	200 req/mo	Sign up
`livegolf_`	Live Golf API	Golf (PGA/DP World)	8	Free tier	Sign up
`isports_`	iSportsAPI	Football/Basketball (Asia)	10	Free tier	Sign up
`sportdevs_`	SportDevs	Rugby/Volleyball/Handball	12	Trial	Sign up
`msf_`	MySportsFeeds	NFL/NBA/MLB/NHL	12	Free non-commercial	Sign up
`golfcourse_`	GolfCourseAPI	30K+ golf courses	6	300 req/day	Sign up
`cfbd_`	College Football Data	NCAA football	14	1000 req/mo	Sign up
`boxing_`	Boxing Data API	Pro boxing (fighters/bouts/titles)	8	100 req/mo	Sign up
`highlightly_`	Highlightly	Multi-sport highlights + odds	6	100 req/day	Sign up

Providers with missing keys don't block the server — they just return an error when called. Register keys incrementally as you need them.

Installation

Quick (npx — no install)

Terminal

npx mcp-sports-hub

npm global

Terminal

npm install -g mcp-sports-hub
mcp-sports-hub

From source

bash

git clone https://github.com/lacausecrypto/mcp-sports-hub.git
cd mcp-sports-hub
npm install
npm run build

MCP Registry

This server is published on the official MCP Registry as io.github.lacausecrypto/sports-hub. MCP clients that support the registry can discover and install it automatically.

Transport Modes

Stdio (default — Claude Desktop, Cursor, etc.)

Terminal

npx mcp-sports-hub

HTTP/SSE (remote clients, web apps, custom integrations)

bash

# Via flag
npx mcp-sports-hub --http

# Via env
SPORTS_HUB_HTTP=1 SPORTS_HUB_PORT=3000 npx mcp-sports-hub

Endpoints:

POST /mcp — MCP protocol (Streamable HTTP with SSE)
GET /health — Health check ({"status":"ok","providers":19,"sessions":0,"mode":"session"})

Supports CORS and multi-client session management via the mcp-session-id header. Default port: 3000.

Each client gets its own session, created on initialize and addressed afterwards by its session id. Building a session costs ~90 ms for the 165-tool free preset, paid once per client rather than per request. Idle sessions are reaped.

bash

SPORTS_HUB_MAX_SESSIONS=200   # concurrent sessions before new ones get a 503
SPORTS_HUB_SESSION_TTL=1800   # seconds a session may sit idle
SPORTS_HUB_STATELESS=1        # opt out: build a throwaway server per request

SPORTS_HUB_STATELESS=1 suits several replicas behind a load balancer with no sticky routing. It pays the build cost on every call, so prefer sessions for a single instance.

⚠ Security: HTTP mode binds to 127.0.0.1 (loopback) by default. Setting SPORTS_HUB_HOST=0.0.0.0 exposes an unauthenticated MCP endpoint to your whole network — anyone who can reach it can use your configured API keys. DNS-rebinding protection only blocks browser-origin attacks, not direct clients. Only expose it behind a reverse proxy with auth/TLS. SPORTS_HUB_CORS_ORIGINS must list explicit origins (a literal * is rejected).

Hosted (Smithery)

A Dockerfile and smithery.yaml are included for container hosting on Smithery. The hosted endpoint serves the keyless free preset, so clients connect with zero setup. The deploy sets SPORTS_HUB_DNS_REBINDING_PROTECTION=0 because Smithery's proxy forwards a non-localhost Host header.

SPORTS_HUB_DNS_REBINDING_PROTECTION=0 disables the Host/Origin check (it is on by default). Only set it when the server runs behind a trusted proxy that owns routing — never for a server directly reachable by browsers on localhost.

Configuration

Environment Variables

Only set keys for providers you want:

server.ts

# Free — no key needed:
# ESPN, NHL, MLB, Jolpica F1, OpenF1, OpenLigaDB, NCAA, TheSportsDB (test key),
# SportSRC (V1), Lichess, Chess.com, Squiggle (AFL),
# MotoGP, Formula E, NASCAR, OpenDota, Sleeper

# Optional (defaults to test key)
export THESPORTSDB_API_KEY="your-key"          # https://www.thesportsdb.com/

# Requires free registration
export PANDASCORE_TOKEN="your-token"            # https://pandascore.co/
export API_SPORTS_KEY="your-key"                # https://api-sports.io/
export API_FOOTBALL_KEY="your-key"              # https://www.api-football.com/
export API_TENNIS_KEY="your-key"                # https://api-tennis.com/
export BALLDONTLIE_API_KEY="your-key"           # https://www.balldontlie.io/
export CRICKETDATA_API_KEY="your-key"           # https://cricketdata.org/
export ENTITY_SPORT_KEY="your-key"              # https://www.entitysport.com/
export FOOTBALL_DATA_API_KEY="your-key"         # https://www.football-data.org/
export SPORTMONKS_API_KEY="your-key"            # https://www.sportmonks.com/
export SPORTSDATA_IO_KEY="your-key"             # https://sportsdata.io/
export THE_ODDS_API_KEY="your-key"              # https://the-odds-api.com/
export ODDS_API_IO_KEY="your-key"               # https://odds-api.io/
export SPORTS_GAME_ODDS_KEY="your-key"          # https://sportsgameodds.com/
export FIGHTING_TOMATOES_API_KEY="your-key"     # https://fightingtomatoes.com/
export LIVE_GOLF_API_KEY="your-key"             # https://livegolfapi.com/
export ISPORTSAPI_KEY="your-key"                # https://www.isportsapi.com/
export SPORTDEVS_API_KEY="your-key"             # https://sportdevs.com/
export GOLFCOURSE_API_KEY="your-key"            # https://golfcourseapi.com/
export MYSPORTSFEEDS_USER="your-user"           # https://www.mysportsfeeds.com/
export MYSPORTSFEEDS_PASS="your-pass"
export CFBD_API_KEY="your-key"                  # https://collegefootballdata.com/key
export LUMIFY_API_KEY="your-key"                # https://lumify.ai/

Windows (PowerShell):

powershell

$env:API_SPORTS_KEY = "your-key"
$env:PANDASCORE_TOKEN = "your-token"

Windows (cmd):

cmd

set API_SPORTS_KEY=your-key
set PANDASCORE_TOKEN=your-token

Response size and the `fields` parameter

Sports APIs return very wide objects, and every byte a tool returns is spent from the model's context window. A single espn_get_scoreboard-style team listing is ~300 KB of JSON, of which the part anyone wants is under 3 KB.

Every tool accepts an optional fields parameter: a comma-separated list of key names to keep, matched at any depth. Branches that match nothing are dropped, and a matched key keeps its whole value.

jsonc

// espn_get_teams { "sport": "basketball", "league": "nba" }
//   -> 297 KB

// espn_get_teams { "sport": "basketball", "league": "nba",
//                  "fields": "id,abbreviation,displayName,location" }
//   -> 2.9 KB, same 30 teams

If fields matches nothing, the tool says so and lists the top-level keys it did see, rather than returning an empty object.

Responses are also capped. Above the limit, the longest lists in the payload are shortened until it fits (so the JSON still parses) and a note reports how many items were dropped.

bash

SPORTS_HUB_MAX_RESULT_BYTES=40000   # default; serialized bytes per tool result

Claude Desktop

Config file locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json

config.json

{
  "mcpServers": {
    "sports-hub": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-sports-hub/dist/index.js"],
      "env": {
        "PANDASCORE_TOKEN": "your-token",
        "API_SPORTS_KEY": "your-key",
        "THE_ODDS_API_KEY": "your-key"
      }
    }
  }
}

Windows path: "args": ["C:/Users/you/mcp-sports-hub/dist/index.js"]

Only include env vars for providers you need. Omit env entirely for free-only providers.

Claude Code (CLI)

Terminal

claude mcp add sports-hub node /absolute/path/to/mcp-sports-hub/dist/index.js

Or in .claude/settings.json:

config.json

{
  "mcpServers": {
    "sports-hub": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-sports-hub/dist/index.js"],
      "env": {
        "PANDASCORE_TOKEN": "your-token"
      }
    }
  }
}

Provider Filtering

By default, only the free preset is loaded (19 providers, ~165 tools — no API keys needed). Use SPORTS_HUB_PROVIDERS to change what's loaded:

bash

# Default — free providers only (no config needed)
npx mcp-sports-hub

# Load ALL 42 providers (410 tools)
SPORTS_HUB_PROVIDERS=all npx mcp-sports-hub

# Use a preset
SPORTS_HUB_PROVIDERS=us-major npx mcp-sports-hub

# Pick specific providers
SPORTS_HUB_PROVIDERS=espn,nhl,odds npx mcp-sports-hub

# Exclude from all (prefix with -)
SPORTS_HUB_PROVIDERS=-sportsdata,-mma npx mcp-sports-hub

Presets

Preset	Providers	Tools	Needs keys?
`free` (default)	19 no-key providers (espn, nhl, mlb, f1, openf1, openliga, sportsdb, ncaa, sportsrc, lichess, chesscom, squiggle, motogp, formulae, nascar, opendota, sleeper, euroleague, footballdatauk)	~165	No
`all`	all 42 providers	410	Yes (for key-required providers)
`chess`	lichess, chesscom	14	No
`us-major`	espn, nhl, mlb, ncaa, cfbd, bdl, msf, nascar, sleeper	~93	Some
`soccer`	espn, apifootball, footballdata, sportmonks, openliga, sportsrc, footballdatauk, highlightly	~73	Some
`f1`	f1, openf1	25	No
`motorsport`	f1, openf1, motogp, formulae, nascar	~42	No
`esports`	pandascore, opendota	25	Some
`odds`	odds, oddsio, sgo, lumify	43	Yes
`cricket`	cricket, entitycricket	22	Yes
`golf`	livegolf, golfcourse	14	Some

Cache

All GET responses are cached in memory for 60 seconds by default. This protects against duplicate calls and rate limit waste. Configure with:

bash

SPORTS_HUB_CACHE_TTL=120  # seconds (0 to disable)

The cache key includes a digest of the request's auth headers, so two API keys never read each other's entries. Concurrent identical requests are collapsed into a single upstream call, and a 404/410 is remembered briefly (SPORTS_HUB_NEGATIVE_CACHE_TTL, default 30s) so a wrong ID can't be re-fetched in a loop.

Rate limits and retries

429 and 5xx responses are retried with exponential backoff, honouring Retry-After when the upstream sends one. Client errors (4xx other than 408/425/429) and timeouts are not retried.

bash

SPORTS_HUB_MAX_RETRIES=2        # extra attempts after the first (0 disables)
SPORTS_HUB_RETRY_BASE_MS=300    # backoff base; doubles per attempt

In Claude Desktop config:

json

"env": {
  "SPORTS_HUB_PROVIDERS": "us-major",
  "THE_ODDS_API_KEY": "your-key"
}

Tool Naming

All tools follow {provider}_{action}:

Code

espn_get_scoreboard        — Live scores (ESPN)
nhl_get_standings          — NHL standings
mlb_get_game_boxscore      — MLB box score
f1_get_race_results        — F1 results (1950+)
openf1_get_laps            — F1 live telemetry
pandascore_get_lives       — Live esports matches
apifootball_get_fixtures   — Soccer fixtures (960+ leagues)
odds_get_odds              — Betting odds (70+ sports)
sportsrc_get_xg_stats      — Expected goals (xG)

MCP Resources & Prompts

Beyond tools, the server exposes:

Resources (readable catalogs, no API call):

sportshub://providers — the full provider catalog (prefix, name, coverage, required key)
sportshub://presets — all presets and the providers they load
sportshub://provider/{key} — details for one provider (with key autocompletion)

Prompts (curated slash-command workflows over the 410 tools):

whats-on-today · compare-odds {event} · motorsport-weekend {series} · league-standings {league} · team-deep-dive {team} · f1-race {season} {round}

All tools are annotated readOnly / idempotent so clients can skip confirmation prompts.

Architecture

Code

src/
├── index.ts                    # Imports + registers all 42 providers; transports
├── shared/
│   ├── http.ts                 # fetchJson, fetchText, buildUrl, toolResult, errorResult
│   │                           #   + retry/backoff, coalescing, keyed cache
│   ├── catalog.ts              # provider catalog + presets (single source of truth)
│   ├── annotations.ts          # central read-only annotations + titles
│   ├── tool-pipeline.ts        # central `fields` param, size cap, empty-result hints
│   ├── projection.ts           # field projection used by the pipeline
│   ├── slim.ts                 # strips $schema boilerplate from tools/list
│   ├── resources.ts            # MCP resources (provider/preset catalogs)
│   └── prompts.ts              # MCP prompts (curated workflows)
└── providers/
    ├── espn.ts                 #  10 tools — no key
    ├── nhl.ts                  #  13 tools — no key
    ├── mlb-stats.ts            #  13 tools — no key
    ├── jolpica-f1.ts           #  13 tools — no key
    ├── openf1.ts               #  12 tools — no key
    ├── openligadb.ts           #  10 tools — no key
    ├── golfcourse.ts           #   6 tools — GOLFCOURSE_API_KEY
    ├── thesportsdb.ts          #  13 tools — optional key
    ├── pandascore.ts           #  14 tools — PANDASCORE_TOKEN
    ├── api-football.ts         #  15 tools — API_FOOTBALL_KEY
    ├── api-sports.ts           #  10 tools — API_SPORTS_KEY
    ├── api-tennis.ts           #  12 tools — API_TENNIS_KEY
    ├── balldontlie.ts          #  10 tools — BALLDONTLIE_API_KEY
    ├── cricketdata.ts          #  10 tools — CRICKETDATA_API_KEY
    ├── entity-sport-cricket.ts #  12 tools — ENTITY_SPORT_KEY
    ├── football-data.ts        #  11 tools — FOOTBALL_DATA_API_KEY
    ├── sportmonks.ts           #  12 tools — SPORTMONKS_API_KEY
    ├── sportsdata-io.ts        #  12 tools — SPORTSDATA_IO_KEY
    ├── the-odds-api.ts         #   9 tools — THE_ODDS_API_KEY
    ├── odds-api-io.ts          #  10 tools — ODDS_API_IO_KEY
    ├── sports-game-odds.ts     #  10 tools — SPORTS_GAME_ODDS_KEY
    ├── lumify.ts               #  14 tools — LUMIFY_API_KEY
    ├── fighting-tomatoes.ts    #   8 tools — FIGHTING_TOMATOES_API_KEY
    ├── live-golf.ts            #   8 tools — LIVE_GOLF_API_KEY
    ├── isportsapi.ts           #  10 tools — ISPORTSAPI_KEY
    ├── sportdevs.ts            #  12 tools — SPORTDEVS_API_KEY
    ├── mysportsfeeds.ts        #  12 tools — MYSPORTSFEEDS_USER/PASS
    ├── sportsrc.ts             #   7 tools — V1 free, V2 needs paid key (not exposed)
    ├── ncaa.ts                 #   8 tools — no key
    ├── cfbd.ts                 #  14 tools — CFBD_API_KEY
    ├── lichess.ts              #   7 tools — no key
    ├── chess-com.ts            #   7 tools — no key
    ├── squiggle.ts             #   6 tools — no key
    ├── motogp.ts               #   7 tools — no key
    ├── formula-e.ts            #   7 tools — no key
    ├── nascar.ts               #   3 tools — no key
    ├── opendota.ts             #  11 tools — no key
    ├── sleeper.ts              #  10 tools — no key
    ├── euroleague.ts           #   6 tools — no key
    ├── football-data-uk.ts     #   2 tools — no key (CSV)
    ├── boxing.ts               #   8 tools — BOXING_DATA_API_KEY
    └── highlightly.ts          #   6 tools — HIGHLIGHTLY_API_KEY

Each provider exports register(server). Keys are checked at call time, not startup.

Contributing

Fork the repository
Create src/providers/my-api.ts exporting register(server: McpServer)
Prefix tool names: myapi_get_something
Import + call in src/index.ts
npm run build to verify
Submit a PR

License

MIT

Sports Hub MCP Server

Demo

Compatibility

Platforms

MCP Clients

Providers (32)

Works instantly — no API key, no signup (19 providers, ~165 tools)

Free tier with API key — signup required, no credit card (23 providers, ~245 tools)

Installation

Quick (npx — no install)

npm global

From source

MCP Registry

Transport Modes

Stdio (default — Claude Desktop, Cursor, etc.)

HTTP/SSE (remote clients, web apps, custom integrations)

Hosted (Smithery)

Configuration

Environment Variables

Response size and the fields parameter

Claude Desktop

Claude Code (CLI)

Provider Filtering

Presets

Cache

Rate limits and retries

Tool Naming

MCP Resources & Prompts

Architecture

Contributing

License

Response size and the `fields` parameter