SportAPI README

sportapi-mcp

An MCP server that lets AI assistants (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf and other MCP clients) look up Live and Prematch matches, scores, live statistics and betting odds from SportAPI. It runs on demo data out of the box, without an API key.

claude mcp add sportapi -- uvx sportapi-mcp

Then ask: "Which football matches are live right now, and who is favoured?"

This MCP server is free and MIT-licensed. The SportAPI data service behind it is a commercial product: live data needs a personal API key (how to get one). Without a key, every tool answers with the example responses from the SportAPI documentation, and every result says so.

Features

• 11 read-only tools covering the Sport Line API: sports, the navigation menu, countries, tournaments, Live and Prematch match lists, the match calendar, full match details with every market, team search, top matches, top championships and the key's account status.
• Token-efficient output: compact JSON with empty fields dropped and odds rendered as one line per market ("W1 1.525 | X 5.08 | W2 6.15"). A detailed match can carry 200+ markets, so get_match returns 15 by default and accepts a markets filter (["1X2", "Total"]).
• Polite by design: every request goes through a snapshot cache that enforces the documented minimum update intervals and never sends overlapping requests for the same data. No tool polls or fans out over matches, however often the assistant calls it.
• Demo mode with no setup, clearly labelled ("source": "demo") so that an assistant never presents a snapshot as live data.
• Actionable errors: an expired key, a sport outside the subscription, a finished match or a game_id from the wrong line type come back as short explanations the assistant can act on.
• Two prompts: a live betting overview for a sport and a market comparison (implied probabilities, bookmaker margin, fair odds) for one match.
• Built on the official SportAPI Python client and the official MCP Python SDK. stdio by default, Streamable HTTP optional.

What you can ask

Example conversations in demo mode (answers abridged). The assistant picks the tools itself.

"What's happening in live football right now?" → list_live_matches(sport_id=1)

Demo data from the SportAPI documentation, not live. 39 football matches are in play. Garuda Darwin 0:1 Darwin Olympic (76', NPL Northern Territory): Darwin Olympic are near-certain winners at 1.064. Ikonnect FA U19 0:1 Obosa U19 (33'): Obosa favoured at 1.40, the draw at 4.65. Caucaia U20 — Floresta EC U20 is goalless at 2', with Floresta slight favourites at 2.112.

"Arsenal against Coventry: how are the goal lines priced?" → get_match(game_id=746146992, line_type="live", markets=["Total"])

Arsenal lead 3:0 at 56' (xG 1.45 vs 0.03, shots on target 4:0). Total goals: Over 3.5 at 1.23, Over 4.5 at 2.09 / Under 4.5 at 1.81, Over 5.5 at 4.41. The market expects a fourth goal but leans against a fifth.

"When does Manchester City play next, and what are the odds?" → search_matches(text="Manchester"), then get_match(game_id=730321837, line_type="prematch", markets=["1X2", "Total"])

Manchester City — Bournemouth, Premier League, 23 Aug 2026 13:00 UTC. 1X2: City 1.525, draw 5.08, Bournemouth 6.15. Over 2.5 goals 1.39, under 2.5 2.72.

"What are the biggest games this weekend?" → top_matches(line_type="prematch", include_odds=True)

"Is my SportAPI key OK, and how many requests did I make this week?" → account_status() (live mode)

With a key, the same questions work for every sport in your subscription, with current data.

Install

The server is a Python package (Python 3.10+). The easiest way to run it is with uv: uvx downloads and runs it in an isolated environment, with no install step.

uvx sportapi-mcp            # starts the stdio server; MCP clients launch it for you

Or install it with pip and use the sportapi-mcp command instead of uvx sportapi-mcp:

pip install sportapi-mcp

The env blocks below are optional: leave them out to start in demo mode.

Claude Desktop

One-click install: download sportapi-mcp.mcpb from the latest release and open it — Claude Desktop installs the extension and asks for the optional key and base URL (leave them empty for demo data). The bundle sources are in mcpb/.

Or edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "sportapi": {
      "command": "uvx",
      "args": ["sportapi-mcp"],
      "env": {
        "SPORTAPI_KEY": "YOUR_API_KEY",
        "SPORTAPI_BASE_URL": "https://YOUR_API_DOMAIN"
      }
    }
  }
}

Restart Claude Desktop; the SportAPI tools appear in the tools menu.

Claude Code

# demo mode
claude mcp add sportapi -- uvx sportapi-mcp

# live data, available in all your projects
claude mcp add sportapi --scope user \
  -e SPORTAPI_KEY=YOUR_API_KEY -e SPORTAPI_BASE_URL=https://YOUR_API_DOMAIN \
  -- uvx sportapi-mcp

Cursor

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "sportapi": {
      "command": "uvx",
      "args": ["sportapi-mcp"],
      "env": {
        "SPORTAPI_KEY": "YOUR_API_KEY",
        "SPORTAPI_BASE_URL": "https://YOUR_API_DOMAIN"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json. VS Code asks for the key once and stores it securely:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "sportapi-key",
      "description": "SportAPI key",
      "password": true
    }
  ],
  "servers": {
    "sportapi": {
      "type": "stdio",
      "command": "uvx",
      "args": ["sportapi-mcp"],
      "env": {
        "SPORTAPI_KEY": "${input:sportapi-key}",
        "SPORTAPI_BASE_URL": "https://YOUR_API_DOMAIN"
      }
    }
  }
}

Windsurf and other clients

Any MCP client that can start a stdio server works: the command is uvx, the argument is sportapi-mcp, and the environment variables are listed below. For Windsurf, put the mcpServers block shown for Cursor into ~/.codeium/windsurf/mcp_config.json.

Streamable HTTP and Docker

sportapi-mcp --transport streamable-http --port 8000      # http://127.0.0.1:8000/mcp

docker build -t sportapi-mcp .
docker run -i --rm -e SPORTAPI_KEY -e SPORTAPI_BASE_URL sportapi-mcp          # stdio
docker run --rm -p 8000:8000 sportapi-mcp --transport streamable-http --host 0.0.0.0

The HTTP transport has no authentication of its own: keep it on localhost or behind your own gateway, because anyone who can reach it uses your key.

Configuration

Set both SPORTAPI_KEY and SPORTAPI_BASE_URL for live data, or neither for demo mode. sportapi-mcp --demo forces demo mode even when a key is configured.

A key is bound to the server IP addresses or sites approved for it (authentication and access). An MCP server usually runs on your own computer, so make sure that address is allowed for the key; account_status shows the IP address SportAPI sees.

Tools

Prompts: live_betting_overview(sport) and compare_match_markets(match, markets).

How the output maps to the API data (decimal odds, blocked selections, market IDs, sub-events, live statistics) is described in the odds, match and live statistics data models. get_match(include_pointers=true) adds each selection's oc_pointer, the code used by bet placement systems such as the SportAPI Coupon API.

Demo mode coverage

Demo mode serves the full English example responses from the SportAPI documentation (snapshots from August–October 2026):

• list_sports, get_menu, top_matches: Live and Prematch;
• list_countries, list_live_matches, list_prematch_matches: football (sport_id 1);
• list_tournaments: football, country_id 1;
• get_match: 746146992 (Live, Arsenal — Coventry City) and 730321837 (Prematch, Manchester City — Bournemouth);
• search_matches: "Perth" (Live) and "Manchester" (Prematch).

Anything else (other sports and matches, the calendar, esports, top_championships) returns a message that lists what demo mode covers and how to get a key.

Update intervals

Every response is a snapshot. The server reuses a snapshot until the documented minimum interval for that method has passed, for example 7 s for the Live match list, 5 s for a Live match and 30 s for a Prematch match. Results served from the cache carry cached_seconds. Concurrent calls for the same data wait for the request already in flight. See the data update guidelines.

Documentation

• Quick start
• API methods overview
• Core concepts: Live vs Prematch, IDs
• Error handling
• Sports and sport IDs
• SportAPI documentation

Building your own integration instead? Use the SportAPI Python client this server is built on.

Get an API key

Live data needs a personal API key and base URL from SportAPI. Plans start from $30/month, with a free 2-day trial.

• Telegram: @sportapinet_bot
• Website: sportapi.net

Keep the key in your MCP client's configuration or a secret store, never in a shared chat or a Git repository.

Contributing

Issues and pull requests are welcome; see CONTRIBUTING.md. Run ruff check . && mypy && pytest before submitting.

License

MIT © 2026 SportAPI