SportWizzard Server

Query live sports-betting data — odds, edges, arbitrage, player/team stats and reference data — from any MCP-capable AI agent (Claude Desktop, Cursor, Claude Code, etc.) using your SportWizzard API key.

This repo ships two transports over the exact same 19-tool set: a hosted remote server (Streamable HTTP at https://mcp.sportwizzard.com/mcp — zero install) and a stdio server you run locally (npx/from source). It wraps the SportWizzard REST v1 API in a curated, read-only set of tools your agent can call.

Hosted (recommended — one command, no install)

claude mcp add --transport http sportwizzard https://mcp.sportwizzard.com/mcp \
  --header "Authorization: Bearer sk_your_key_here"

Codex CLI:

codex mcp add sportwizzard --transport http --url https://mcp.sportwizzard.com/mcp \
  --header "Authorization: Bearer sk_your_key_here"

Get a key at https://sportwizzard.com/account. The hosted server is a thin proxy — your bearer key is forwarded as X-Api-Key on every REST call, so auth, rate limiting and (future) billing are enforced by the same SportWizzard API the key already works against. The server holds no privileged credentials of its own and exposes 19 of the 20 tools below (download_snapshot is stdio-only — it writes to your filesystem, which doesn't make sense on a hosted multi-tenant server; use the stdio path below if you need it).

Status: the stdio npx path below is not yet published to npm (see npm publish status). The hosted path above works today regardless.

Stdio (local process)

This is a Model Context Protocol stdio server you run yourself.

Until npm publish lands, install straight from GitHub — npx -y github:adamruehle/sportwizzard-mcp works today, no clone/build step required, and is what the commands below use. Once published, swap github:adamruehle/sportwizzard-mcp for sportwizzard-mcp — everything else is unchanged.

Quick start

npx -y github:adamruehle/sportwizzard-mcp

Set your API key via the SPORTWIZZARD_API_KEY environment variable. Get a key at https://sportwizzard.com/account.

While SportWizzard is in its pre-billing public phase the data endpoints are open, so the tools also work without a key. Once metering is enabled a missing/invalid key returns a clear error.

Claude Desktop

Add this to your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "sportwizzard": {
      "command": "npx",
      "args": ["-y", "github:adamruehle/sportwizzard-mcp"],
      "env": {
        "SPORTWIZZARD_API_KEY": "sk_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. You'll see the SportWizzard tools available in the chat.

Claude Code / Codex CLI

claude mcp add sportwizzard -e SPORTWIZZARD_API_KEY=sk_your_key_here -- npx -y github:adamruehle/sportwizzard-mcp

Try it without a key (mock mode)

Set SPORTWIZZARD_MOCK=1 to return canned sample responses — no key, no network. Great for wiring things up before you have a key:

{
  "mcpServers": {
    "sportwizzard": {
      "command": "npx",
      "args": ["-y", "github:adamruehle/sportwizzard-mcp"],
      "env": { "SPORTWIZZARD_MOCK": "1" }
    }
  }
}

npm publish status

npm view sportwizzard-mcp still 404s — the package name is free but not yet claimed. Publishing needs a one-time interactive npmjs.com account setup (npm no longer allows creating a new account from the CLI — npm adduser requires a real TTY and, on npmjs.com's side, completing signup through the website, which is CAPTCHA-gated). This can't be scripted headlessly. To unblock (~2 minutes, one time, human required):

1. Go to https://www.npmjs.com/signup and create an account (suggested: username sportwizzard, email [email protected]) — solve the CAPTCHA, verify the email.
2. On this machine: npm login (opens a browser tab to confirm the login — approve it) or npm adduser and follow the prompts.
3. npm whoami should print the new username.
4. From sportwizzard-mcp/: npm publish (the prepare script builds automatically).
5. Flip the two npx -y github:adamruehle/sportwizzard-mcp commands in this README back to npx -y sportwizzard-mcp, and delete this section.

Once logged in, all future publishes (version bumps) are just npm version patch && npm publish — no CAPTCHA involved after the account exists.

Configuration

Env var	Default	Purpose
SPORTWIZZARD_API_KEY	(none)	Your SportWizzard API key, sent as the X-Api-Key header.
SPORTWIZZARD_BASE_URL	https://api.sportwizzard.com	Override the API base URL (e.g. for local testing).
SPORTWIZZARD_MOCK	(off)	Set to 1 to return canned sample data instead of calling the API.

Tools

Tool	Endpoint	What it does
list_events	GET /api/v1/events	List events/fixtures — the spine. Filter by league, team_id, status, starts_after/before; paginate with cursor.
get_event	GET /api/v1/events/{id}	Full event detail: venue, season, scores, and game context (weather, lineups, probable pitchers, officials).
get_event_stats	GET /api/v1/events/{id}/stats	The box score: every player's stat line + the team result row for one event.
get_event_odds	GET /api/v1/events/{id}/odds	Every sportsbook price for one event (flat rows: book × market × selection).
get_odds	GET /api/v1/odds	Core odds query, scoped by event_id / player_id / team_id / sportsbook / market / league.
get_player_odds	GET /api/v1/players/{id}/odds	All current prices for one player (props).
get_team_odds	GET /api/v1/teams/{id}/odds	All current prices for one team.
get_edges	GET /api/v1/edges	+EV edges vs. devigged fair market. Filter by league, source, min_edge, event_id.
get_arbitrage	GET /api/v1/arbitrage	Arbitrage opportunities with legs + stake fractions. Filter by type (two_way/three_way), min_profit.
list_players	GET /api/v1/players	Players reference. Filter by league/team.
list_teams	GET /api/v1/teams	Teams reference. Filter by league.
get_player_stats	GET /api/v1/players/{id}/stats	Player season/historical stats.
get_team_stats	GET /api/v1/teams/{id}/stats	Per-game team stats/results, optionally scoped to a season.
get_player_game_logs	GET /api/v1/stats/players	Bulk per-game player stat rows (game logs) by player/team/event — the model-training feed.
get_account_usage	GET /api/v1/account/usage	Your plan tier, rate limit, and monthly usage.
download_snapshot	GET /api/v1/snapshot	Downloads the FULL live board (tens of MB gzip, 80k+ markets) to a file — you provide save_path; it never enters the context window. .gz path keeps gzip, otherwise decompressed JSON. Returns path/bytes/etag; pass the etag back to skip unchanged downloads (304).
list_sportsbooks	GET /api/v1/sportsbooks	Sportsbooks/DFS platforms tracked, with live market counts.
list_leagues	GET /api/v1/leagues	Leagues currently covered.
list_markets	GET /api/v1/markets	Supported market types, with live counts.
status	GET /api/v1/status	Total live markets + active sportsbook count.

Every response uses the SportWizzard envelope { success, data, nextCursor, meta }. When a nextCursor is present the tool appends a _paging hint so the agent knows to call again with cursor=....

From source

git clone https://github.com/adamruehle/sportwizzard-mcp.git
cd sportwizzard-mcp
npm install
npm run build
SPORTWIZZARD_MOCK=1 node dist/index.js   # or set SPORTWIZZARD_API_KEY

Point your MCP client's command at node and args at the absolute path to dist/index.js.

License

MIT © SportWizzard LLC