Sportwizzard MCP Server

SportWizzard MCP Server

Query live sports-betting data — odds, player props, +EV edges, arbitrage, stats and reference data from 35+ sportsbooks and DFS apps — from any MCP-capable AI agent (Claude Code, Claude Desktop, Codex, Cursor, …).

20 read-only tools over the SportWizzard REST v1 API, available two ways: a hosted remote server (zero install) and a stdio server via npx. Get a free API key at https://sportwizzard.com/account (API Keys tab — no card required).

Hosted (recommended — zero install)

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

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

The hosted server is a thin proxy: your key is forwarded to the SportWizzard API, which enforces auth and rate limits. All 20 tools work on both transports. (download_snapshot on the hosted server returns a CDN download URL + a ready-to-run command your agent executes locally; on stdio it writes the file directly.)

Successful authenticated live tool calls send a best-effort account-usage receipt. The measurement request contains no tool arguments or result data. For hosted download_snapshot, a successful CDN HEAD check counts because the tool has verified that the returned download URL is reachable; a failed HEAD check does not count.

Stdio (local)

npx -y sportwizzard-mcp

Claude Code:

claude mcp add sportwizzard -e SPORTWIZZARD_API_KEY=sw_live_your_api_key_here -- npx -y sportwizzard-mcp

Claude Desktop (claude_desktop_config.json — macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "sportwizzard": {
      "command": "npx",
      "args": ["-y", "sportwizzard-mcp"],
      "env": { "SPORTWIZZARD_API_KEY": "sw_live_your_api_key_here" }
    }
  }
}

Mock mode (no key, no network)

Set SPORTWIZZARD_MOCK=1 to get canned sample responses — useful for wiring up an integration before you have a key.

Configuration

Tools

Every response uses the envelope { success, data, nextCursor, meta }; when nextCursor is present the tool appends a _paging hint so agents know to continue.

Participants and sides

Events, edges and arbitrage rows list who takes part as participants, ordered by side:

get_event adds each side's final score and, when a source reported one, the latest live state ({status, period, clock, side1Score, side2Score, source, observedAt}).

Each odds row is one outcome of a selection:

• side: 1 or 2, the event side the outcome is about; absent for totals, draws, "neither" and futures.
• outcomeCode: SportWizzard's fixed list: OVER, UNDER, YES, NO, WIN (a moneyline leg is WIN with its side), DRAW, NEITHER, WIN_OR_DRAW, EITHER, ODD, EVEN, SCORE (read side1Score/side2Score), RANGE, OTHER, LABEL (a categorical answer only the selection label explains).
• statType: the fixed stat list (points, rush_yards, …).
• outcomeParticipants: [{kind: "competitor" | "player", name}], names exactly as the sportsbook sent them. An outcome about a side with no name has none; read the event participant on that side.

Markets carry phase (PRE or LIVE). With include_history, each selection's selectionPrice is a list of rows, oldest first, one per run of an unchanged price:

{"observedAt": "2026-11-03T12:31:02Z", "lastObservedAt": "2026-11-03T12:40:15Z", "priceAmerican": -110, "priceDecimal": 1.9091}

A row may also carry dfsMultiplier, suspended: true and, on exchanges, liquidityTier.

IDs depend on your key: with an API key on a paid plan, each participant and outcome participant also has competitorId (a team) or playerId (a person), and odds, edge and arbitrage rows carry playerId and source references. Without a key, or on the Free plan, you get names and sides. competitor_id and player_id filters match events where that competitor or player is a participant.

Futures (season-scope markets)

get_odds with scope=season returns season-long futures — division/conference/championship winners, award odds, team win totals, season leaders and full-season player props. Three orthogonal axes describe them:

• marketScope — which anchor the market hangs off: SEASON or TOURNAMENT. Omitted entirely on ordinary game rows.
• period — the window within that anchor: REG_SEASON (settles at the end of the regular season) or FULL (runs through the playoffs).
• segment — which slice of the competition: AFC_EAST, NL, SEC, … Present only when the market is segment-scoped, and load-bearing: all 32 NFL DIVISION_WINNER selections share one season-anchor eventId, so without segment they read as a single 32-team race instead of 8 divisions.

Notes: winner/award markets are categorical (one YES selection per competitor, no side, usually no NO side); eventStartTime on a futures row is the season anchor / settlement date, not a kickoff; every book's futures for a competition share the same season eventId; and futures are deliberately excluded from get_edges / get_arbitrage (they never enter de-vig or edge math). Scope matching is exact — season does not include TOURNAMENT — and an invalid value returns HTTP 400 naming the valid ones.

From source

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

Maintainers

This README ships inside the npm package, so keep it free of internal hostnames, keys and private notes (the repository is public).

Layout. src/index.ts is the stdio entry (dist/index.js, the npm bin); src/httpServer.ts is the hosted Streamable HTTP entry (stateless, one request per POST; Host allow list and bearer-key handling); src/auth.ts validates the caller's key against the API, caches it and applies the per-key rate limit; src/tools.ts and src/server.ts define and register tools; src/client.ts is the REST client and src/mock.ts the SPORTWIZZARD_MOCK=1 data. tests/stdio-smoke.mjs and tests/http-smoke.mjs are end-to-end smokes against a loopback mock API (no credentials, no production calls).

Build and verify (the PR check, .github/workflows/ci.yml, runs the same pack-and-smoke plus a no-push container build):

npm ci --ignore-scripts && npm run build
release_dir="$(mktemp -d)"
npm pack --ignore-scripts --pack-destination "$release_dir"
npm install --prefix "$release_dir/consumer" --omit=dev --ignore-scripts --no-audit --no-fund "$release_dir"/*.tgz
npm run smoke -- "$release_dir/consumer/node_modules/sportwizzard-mcp/dist/index.js" "$release_dir/smoke.json" "$release_dir"/*.tgz
npm run smoke:http -- "$release_dir/consumer/node_modules/sportwizzard-mcp/dist/httpServer.js" "$release_dir/http-smoke.json"
rm -rf "$release_dir"

The stdio smoke checks tools/list, get_odds scope=season forwarding and a snapshot download with history; the HTTP smoke checks /healthz, key rejection, the Host allow list, tools/list, key forwarding and a clean SIGTERM exit. Both prove transport and packaging, not live data quality.

Releasing.

• Hosted server: publish-container.yml publishes a SHA-tagged GHCR image on every push to main. It deploys only when that digest is promoted in the Ops deployment/releases/api.yaml row, which owns placement, limits and credential references.
• npm package: bump version in package.json, run npm install --package-lock-only, sync server.json, merge to main, then run the manual Publish npm package workflow (publish-npm.yml). It builds once, smokes the packed tarball and publishes those exact bytes through npm trusted publishing (OIDC; no npm token). Publishing npm does not update the hosted container.

Gotchas. Hosted runtime settings are MCP_HTTP_PORT (default 8091), MCP_ALLOWED_HOSTS, AUTH_CACHE_TTL_MS, RATE_LIMIT_PER_MIN, SPORTWIZZARD_SNAPSHOT_URL and SPORTWIZZARD_SNAPSHOT_HISTORY_URL, plus the customer settings above. download_snapshot writes a file on stdio but returns a CDN URL and a command on the hosted server. Never print or commit ~/.npmrc. Open work goes in GitHub issues in this repository.

License

MIT © SportWizzard LLC