Introduction

When developing agents based on Claude, Cursor, or DeepSeek Harness, integrating sports data often means writing crawlers or parsing HTML. This plugin provides football data services directly to these agents through the MCP (Model Context Protocol) standard interface. It requires no API Key and covers historical and real-time data for 18 European leagues and 8 cup competitions.

Positioning

howillmakeit/football-mcp is a football data MCP server for DeepSeek Harness, Claude, Codex, and Cursor. It solves the interface integration challenges when agents need to obtain structured football data (scores, standings, odds, head-to-head records, etc.).

Core Features

The plugin provides the following tool interfaces:

  • list_competitions()
    View all supported leagues and their codes.
  • list_teams(competition, season)
    Query all team codes for a league in a given season. This is a necessary step before filtering by team.
  • get_matches(...)
    Query match results or schedules. Supports filtering by team, date, and played/unplayed status, and can retrieve shots, corners, red and yellow cards, as well as opening and closing 1X2 odds from about 20 bookmakers.
  • get_standings(competition, season, as_of_date?)
    Query league standings. Using the as_of_date parameter allows looking back at the standings on a specific past date.
  • get_team_form(team, ...)
    Query a team’s record over its last N matches, including wins, draws, losses, goals scored and conceded, and average points.
  • get_head_to_head(a, b, ...)
    Query historical head-to-head records between two teams, including wins, draws, losses, and goal counts. Supports grouping by league, cup, or specific event.
  • list_cup_competitions()
    View the list of supported cup competitions.
  • get_cup_matches(...)
    Query cup match pairings, including handling logic for penalty shootouts.

Installation and Enablement

In a DeepSeek Harness environment, install it via the command line:

dsh plugin --profile web add football-data-mcp

After installation, the tools will be available in DSH sessions as interfaces in the mcp__football__* format.

Prerequisites:
* Node.js ≥ 18
* uv (Python server dependency, must be available in the PATH environment variable)

Typical Usage

Query the El Clásico win rate between Barcelona and Real Madrid over the past 10 seasons, including league and cup matches:

get_head_to_head("Barcelona", "Real Madrid", "SP1", "2025-26", seasons_back=9, scope="all")

The system returns detailed statistics for 25 meetings: 12 wins for Barcelona (48%), 9 wins for Real Madrid (36%), and 4 draws. The data will be listed separately by league and cup.

Notes

  • Penalty Shootouts: In head-to-head statistics, a penalty shootout win is counted directly as a win for the team that wins on penalties (disclosed through the pen_wins_a/b fields).
  • Goal Statistics: Only goals scored during regular time and extra time are counted.
  • Standings: Administrative deductions are not included (this type of information is not provided in the source data).
  • Local Dependencies: The plugin requires a Python environment and is launched via uv.

Summary

howillmakeit/football-mcp is a lightweight data provider focused on mainstream European football competitions. Through the standard MCP interface, it transforms data from football-data.co.uk and ESPN into tools that agents can call directly. For developers building sports analytics Agents, this is a practical solution that does not require additional API Key configuration.