# Football MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes live football
data to any MCP client (Claude Desktop, Cursor, the MCP Inspector) as callable tools. It wraps the
[football-data.org](https://www.football-data.org) REST API and lets an AI assistant answer
questions like *"what World Cup matches are on today?"* or *"who are the top scorers in the
Premier League?"* by calling real tools instead of guessing.

Built with Python, [`uv`](https://docs.astral.sh/uv/), and the official MCP SDK's FastMCP.

## What it does

The server registers two tools:

| Tool | Input | Returns |
|------|-------|---------|
| `todays_matches` | none | Today's fixtures across the competitions on your API plan (home/away teams, score, status, kickoff time, competition, matchday) |
| `competition_top_scorers` | `competition_code` (e.g. `WC`, `PL`) | The **season-to-date** leading scorers for that competition (player, team, goals, assists, penalties) |

Both tools shape the API's verbose response down to the fields that matter, validate/handle
failures gracefully, and document their limitations in their docstrings so the model uses them
honestly.

### Supported competition codes

The free football-data.org tier covers 12 competitions:

| Code | Competition | Code | Competition |
|------|-------------|------|-------------|
| `WC` | FIFA World Cup | `FL1` | Ligue 1 |
| `CL` | UEFA Champions League | `ELC` | Championship |
| `BL1` | Bundesliga | `PPL` | Primeira Liga |
| `DED` | Eredivisie | `EC` | European Championship |
| `BSA` | Brasileirão Série A | `SA` | Serie A |
| `PD` | La Liga (Primera División) | `PL` | Premier League |

## Setup

**1. Clone and install dependencies**

```bash
git clone <your-repo-url>
cd mcp-football
uv sync
```

**2. Get a free API token**

Register at [football-data.org](https://www.football-data.org/client/register). The free tier
allows 10 requests/minute across the 12 competitions above.

**3. Add your token to a `.env` file**

```
FOOTBALL_DATA_TOKEN=your_token_here
```

`.env` is gitignored — the token never enters source control. The code reads it from the
environment at runtime via `python-dotenv`.

## Running it

**Test/debug with the MCP Inspector:**

```bash
uv run mcp dev server.py
```

Open the printed URL, click **Connect**, and you can call each tool by hand and inspect the JSON.

**Wire it into Claude Desktop:**

Open **Settings → Developer → Edit Config** and add a `football` entry under `mcpServers`. Use the
absolute path to your `uv` binary (`which uv`) and your project directory:

```json
{
  "mcpServers": {
    "football": {
      "command": "/absolute/path/to/uv",
      "args": ["run", "--directory", "/absolute/path/to/mcp-football", "server.py"],
      "env": { "FOOTBALL_DATA_TOKEN": "..." }
    }
  }
}
```

The `--directory` flag is required so `uv` loads this project's environment (where the dependencies
are installed). Fully quit and reopen Claude Desktop, then ask it something like *"who's scored at
the World Cup so far?"* and it will call the tools on its own.

## Design decisions

A few choices worth calling out:

**Why MCP.** An MCP tool returns the same structured JSON on every call, so the model and any code
built on top of it can depend on the shape. The bigger payoff is general: the same wiring lets a
model reach private databases and authenticated APIs it otherwise couldn't touch at all. For this
project the data is just public football scores, so MCP isn't strictly necessary here. The goal was
to learn the pattern on a friendly, no-stakes source before applying it somewhere it actually
matters.

**Scoped each tool to what the data honestly supports.** Scores read `null` until kickoff and
`winner` reads `null` until the final whistle. The tools pass those nulls straight through instead
of inventing values, and the docstrings say so. That keeps the model from hallucinating results the
source never provided.

**Validate input before spending an API call.** `competition_top_scorers` checks the code against
the 12 valid ones *before* it touches the network, and returns a helpful error listing the allowed
codes if it doesn't match. That keeps a guaranteed 404 from wasting one of the 10/minute requests,
and hands the model something it can act on.

**Graceful failure over crashes.** Both tools wrap their requests in `try`/`except`, separate HTTP
errors (with a rate-limit hint on a 429) from connection errors, and return an `{"error": ...}` dict
the model can relay instead of throwing a traceback the client can't read.

## Limitations & future work

- **Data accuracy is bounded by the upstream feed.** The tools faithfully return whatever
  football-data.org holds; on the free tier, player metadata (shirt numbers, positions) is sparse
  and live attributions can lag mid-tournament.
- **Scorers are season-cumulative, not per-match.** A natural next tool would fetch match detail
  (`/v4/matches/{id}`, chaining off the `id` from `todays_matches`) to get the goalscorers of a
  specific game.
- **Local stdio only.** This runs as a local subprocess for the Claude Desktop demo. Deploying it
  remotely (streamable-HTTP on a host) would mean moving the token to the host's secret store and
  thinking about shared rate limits across users.