Football MCP Server

A Model Context Protocol 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 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, 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

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

2. Get a free API token

Register at football-data.org. 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:

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:

{
  "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.