football-api-mcp

MCP (Model Context Protocol) server for the 5DollarFootballAPI — gives Claude, ChatGPT, Cursor and any MCP-capable AI assistant live football (soccer) data: fixtures, live scores, standings, statistics, betting odds and the full odds movement history, including corner and card lines.

Ask your assistant things like:

• "What Premier League matches are on today, and what are the current scores?"
• "Show the corner standings for league 39 this season."
• "How did the 1x2 odds move for fixture 1234567 before kickoff?"

Setup

You need an API key from 5dollarfootballapi.com — the free tier (no card) covers fixtures, live scores and standings; odds tools need a paid plan (from $5/mo).

Claude Code

claude mcp add football-api -e FIVEDOLLARFOOTBALL_API_KEY=fb_live_your_key -- npx -y football-api-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "football-api": {
      "command": "npx",
      "args": ["-y", "football-api-mcp"],
      "env": { "FIVEDOLLARFOOTBALL_API_KEY": "fb_live_your_key" }
    }
  }
}

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "football-api": {
      "command": "npx",
      "args": ["-y", "football-api-mcp"],
      "env": { "FIVEDOLLARFOOTBALL_API_KEY": "fb_live_your_key" }
    }
  }
}

ChatGPT (Developer mode)

ChatGPT only connects to remote MCP servers (Streamable HTTP over HTTPS), not local stdio commands, and needs a Plus/Pro/Business plan with Developer mode enabled. Run the server in HTTP mode and expose it with a tunnel:

FIVEDOLLARFOOTBALL_API_KEY=fb_live_your_key npx -y football-api-mcp --http --token pick-a-secret
# in another terminal — any tunnel works, e.g. cloudflared or ngrok
cloudflared tunnel --url http://localhost:3333

Then in ChatGPT (verified 2026-08): Settings → Security and login → Developer mode (toggle on), open Plugins in the sidebar, click the + (Create app), and in the New Plugin form set Connection to Server URL, paste https://<your-tunnel-host>/mcp/pick-a-secret, set Authentication to No Auth, tick the acknowledgement and Create, then Connect. --token matters here: ChatGPT cannot send custom headers, so the secret in the path is what keeps a leaked tunnel URL from spending your API key.

Options: --host (default 127.0.0.1), --port (default 3333), or the equivalent MCP_HTTP_HOST / MCP_HTTP_PORT / MCP_HTTP_TOKEN environment variables. The same HTTP mode works for any other remote-only MCP client.

Tools

| Tool | What it does | |---|---| | get_fixtures | Fixtures for a calendar day (default today, UTC) with live scores, corners, cards | | get_fixture | One fixture, optionally with the event timeline and match statistics | | get_fixture_odds | Current odds: 1x2, Asian handicap, goal line, corner line, card lines, BTTS | | get_odds_history | Every recorded price tick for a fixture and market — pre-match and in-play | | get_bookmakers | Bookmaker slugs usable in the odds tools | | get_standings | League table — points, corner or card standings | | search_leagues / search_countries | Discover league and country ids by name | | get_league_fixtures | A league season's fixtures and results | | get_team_fixtures | A team's matches, most recent first | | get_account_status | Your plan, usage and rate-limit state |

Prompts

One-shot analysis templates you can invoke from any prompt-aware client:

| Prompt | What it produces | |---|---| | todays-briefing | A grouped briefing of the day's fixtures, live scores and standout numbers | | odds-movement-report | Opening vs closing analysis of one fixture's market with in-play reaction | | corner-scout | A league's corner tendencies from its corner standings and recent results |

Resources

Attachable context data: football://leagues/popular (popular league ids) and football://bookmakers (bookmaker slugs for the odds tools).

All tools are read-only. Errors come back as tool errors with the API's error code and request id, so the assistant can explain what went wrong.

Development

npm install
npm test          # in-memory MCP client/server tests, no network
FIVEDOLLARFOOTBALL_API_KEY=... npm start          # run over stdio
FIVEDOLLARFOOTBALL_API_KEY=... npm start -- --http # run over Streamable HTTP

The underlying HTTP client is the official fivedollarfootball package. Endpoint reference: 5dollarfootballapi.com/docs.

License

MIT