# football-api-mcp

[![MCP Badge](https://lobehub.com/badge/mcp/5dollarfootball-api-football-api-mcp)](https://lobehub.com/mcp/5dollarfootball-api-football-api-mcp)

MCP (Model Context Protocol) server for the [5DollarFootballAPI](https://5dollarfootballapi.com) — 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](https://5dollarfootballapi.com) — the free tier (no card) covers fixtures, live scores and standings; odds tools need a paid plan (from $5/mo).

### Hosted (nothing to install)

Use the hosted server at `https://mcp.5dollarfootballapi.com` — your API key is the only setup. Every call is made with your own key and counts against your own plan.

**Claude (web, desktop, mobile) and ChatGPT** — add a custom connector (remote MCP server) and paste this as the server URL. No OAuth or other sign-in is involved; the key in the URL is the credential:

```
https://mcp.5dollarfootballapi.com/mcp/fb_live_your_key
```

**Claude Code, Cursor and other clients that can send headers** — keep the key out of the URL:

```bash
claude mcp add --transport http football-api https://mcp.5dollarfootballapi.com/mcp --header "Authorization: Bearer fb_live_your_key"
```

The URL with your key in it is a secret: anyone who has it can spend your quota. Create a separate key for it in your dashboard, and delete that key if the URL ever leaks.

Prefer to run it yourself? The local setups below work the same way.

### Claude Code

```bash
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`:

```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):

```json
{
  "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. The quickest
route is the [hosted server](#hosted-nothing-to-install): use
`https://mcp.5dollarfootballapi.com/mcp/fb_live_your_key` as the Server URL in the steps below
and skip the tunnel. To run your own instead, start the server in HTTP mode and expose it
with a tunnel:

```bash
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.

To serve many users from one instance (what the hosted server runs), use `--hosted` instead of `--http`: no server-side API key, each caller supplies their own as `/mcp/<api-key>` or `Authorization: Bearer <api-key>`. Put it behind a reverse proxy that terminates TLS and keeps the path out of the access log.

## 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

```bash
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
npm start -- --hosted                              # multi-user HTTP, callers bring their own key
```

The underlying HTTP client is the official [`fivedollarfootball`](https://www.npmjs.com/package/fivedollarfootball) package. Endpoint reference: [5dollarfootballapi.com/docs](https://5dollarfootballapi.com/docs).

## License

[MIT](LICENSE)