Provides tools to retrieve today's fixtures and top scorers for the FIFA World Cup.
Provides tools to retrieve today's fixtures and top scorers for the Premier League.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-football what are today's football matches?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
The server registers two tools:
Tool | Input | Returns |
| none | Today's fixtures across the competitions on your API plan (home/away teams, score, status, kickoff time, competition, matchday) |
|
| 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.
The free football-data.org tier covers 12 competitions:
Code | Competition | Code | Competition |
| FIFA World Cup |
| Ligue 1 |
| UEFA Champions League |
| Championship |
| Bundesliga |
| Primeira Liga |
| Eredivisie |
| European Championship |
| Brasileirão Série A |
| Serie A |
| La Liga (Primera División) |
| Premier League |
Related MCP server: MCP Partidos de Fútbol
1. Clone and install dependencies
git clone <your-repo-url>
cd mcp-football
uv sync2. 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.
Test/debug with the MCP Inspector:
uv run mcp dev server.pyOpen 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.
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.
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.
This function, competition_top_scorers sends a httpx request to:
https://api.football-data.org/v4/competitions/{competition_code}/scorers
to find the total scorers in the specified competition.
Please note that only the following competitions are included, and using any
other competition code will result in an error. Use the following competition
codes only:
| WC | FIFA World Cup
| CL | UEFA Champions League
| BL1 | Bundesliga
| DED | Eredivisie
| BSA | Campeonato Brasileiro Série A
| PD | Primera Division
| FL1 | Ligue 1
| ELC | Championship
| PPL | Primeira Liga
| EC | European Championship
| SA | Serie A
| PL | Premier League
Input:
competition_code - the league/tournament that we want to pull scorers from.
Output: a list containing entries about scorers
of the day including the following features:
'event', 'player_name', 'player_num',
'player_position', 'player_team', 'player_goals'
'player_assists', 'player_penalties'
| Name | Required | Description | Default |
|---|---|---|---|
| competition_code | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes that it sends a GET request and returns a list with specific fields, but does not mention rate limits, authentication, or potential side effects. Absence of annotations shifts burden to description, which meets basic needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, but includes a lengthy table of valid codes. Efficient for a single-purpose tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers input constraints and output features adequately for a simple read tool with an output schema. Could mention if pagination exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description adds meaning by defining 'competition_code' and listing valid codes, compensating fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it finds total scorers for a competition via a specific API endpoint. Distinguishes from sibling 'todays_matches' by focusing on scorers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists valid competition codes and warns that others will cause errors, providing clear usage constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
This tool, todays_matches, sends a httpx get request to https://api.football-data.org/v4/matches,
and pulls various data on todays soccer matches (games). This is good to use in case a user wants to know
what the schedule and score of soccer games is today.
Available competitions: | WC | FIFA World Cup
| CL | UEFA Champions League
| BL1 | Bundesliga
| DED | Eredivisie
| BSA | Campeonato Brasileiro Série A
| PD | Primera Division
| FL1 | Ligue 1
| ELC | Championship
| PPL | Primeira Liga
| EC | European Championship
| SA | Serie A
| PL | Premier League
input: None
output: a list containing entries with info on home/away
team, score, date, status (game in play, timed,
finished), winner (None if not finished), the event
(like world cup), and current match day of the season/event.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It discloses that it sends a GET request and returns specific fields, but lacks details on potential limitations like rate limits, authentication, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a main sentence followed by a list of competitions. It is somewhat lengthy but each part adds value, though it could be more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no nested objects), the description covers the purpose, output format, and available competitions. It is adequate for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and the description explicitly notes 'input: None'. Schema coverage is 100%, so no additional parameter semantics needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches soccer match data for today via an API call, listing output fields and available competitions, distinguishing it from the sibling tool competition_top_scorers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says it is useful when a user wants to know today's soccer schedule and scores. It does not state when not to use it or mention alternatives, but the sibling tool has a different purpose, so confusion is unlikely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The two tools have clearly distinct purposes: one retrieves top scorers for a competition, the other fetches today's matches. There is no overlap or ambiguity.
Both tool names use a descriptive, snake_case format similar to 'noun_verb' or 'adjective_noun'. The apostrophe in 'todays_matches' is a minor inconsistency, but overall naming is consistent.
Only two tools for a football data server is too few. Typical football APIs cover many more endpoints such as team info, standings, player stats, match details, etc. The tool count is insufficient for the domain's scope.
The server provides only two operations: top scorers and today's matches. Lacks essential features like team lookup, league tables, player season stats, match details by ID, and historical data. Significant gaps in coverage.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
API-Football MCP — comprehensive soccer/football data
Football-Data.org MCP — soccer competitions, matches, standings
OpenLigaDB MCP — community-run, keyless football / soccer match data.
Historical football results, teams, competitions and draw/streak statistics via 10 read-only tools.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/leandersen/MCP-Football'
If you have feedback or need assistance with the MCP directory API, please join our Discord server