API-Football MCP Server

An MCP (Model Context Protocol) server that wraps the API-Football v3 REST API, exposing football/soccer data as MCP tools. Built with Python and FastMCP.

Features

• 40+ MCP tools covering teams, players, fixtures, standings, transfers, odds, and more
• Streamable HTTP, SSE, and stdio transports
• Async HTTP client with rate-limit tracking and error handling
• Docker support for easy deployment

Prerequisites

• Python 3.13+
• An API-Football API key (get one at api-football.com)

Setup

1. Clone the repository:

   git clone https://github.com/YOUR_USERNAME/API-Football.git
   cd API-Football

2. Install dependencies:

   pip install -r requirements.txt

3. Configure your API key:

   cp .env.example .env

   Edit .env and add your API-Football key:

   API_FOOTBALL_KEY=your_api_key_here
   

Running the Server

# Default: streamable-http on port 8111
python server.py

# Stdio transport (for direct MCP client piping)
python server.py --transport stdio

# SSE transport on a custom port
python server.py --transport sse --port 9000

# Custom host and port
python server.py --host 127.0.0.1 --port 3000

The MCP endpoint will be available at http://localhost:8111/mcp.

Docker

# Using docker compose
docker compose up -d

# Or build and run manually
docker build -t api-football-mcp .
docker run -d -p 8111:8111 --env-file .env --name api-football-mcp api-football-mcp

# Or use the deploy script (builds, runs, and health-checks)
./deploy.sh

MCP Client Configuration

To connect this server to an MCP client, add it to your MCP config:

Streamable HTTP (remote/Docker):

{
  "mcpServers": {
    "api-football": {
      "type": "streamable-http",
      "url": "http://localhost:8111/mcp"
    }
  }
}

Stdio (local):

{
  "mcpServers": {
    "api-football": {
      "type": "stdio",
      "command": "python",
      "args": ["server.py", "--transport", "stdio"],
      "cwd": "/path/to/API-Football",
      "env": {
        "API_FOOTBALL_KEY": "your_api_key_here"
      }
    }
  }
}

Available Tools

Search / Name Resolution

Use these first to find IDs by name, then pass IDs to other tools.

Tool	Description
search_team	Search for a team by name (e.g., "Manchester", "Barcelona")
search_player	Search for a player by name (requires league or team + season)
search_league	Search for a league/competition by name
search_coach	Search for a coach/manager by name
search_venue	Search for a stadium/venue by name

Reference Data

Tool	Description
get_timezones	List all supported timezones
get_countries	List or search countries
get_seasons	List all available seasons
get_leagues	Get league info by ID, name, country, or season

Teams

Tool	Description
get_teams	Get team info by ID, name, league, country, or search
get_team_statistics	Detailed team stats for a league and season (form, goals, cards, lineups)
get_team_seasons	List available seasons for a team
get_team_countries	List all countries with teams

Players

Tool	Description
get_players	Get player info and season statistics
get_player_squads	Get current squad for a team, or find a player's team
get_player_seasons	List available seasons for a player
get_top_scorers	Top goal scorers for a league and season
get_top_assists	Top assist providers for a league and season
get_top_yellow_cards	Players with most yellow cards in a league and season
get_top_red_cards	Players with most red cards in a league and season

Fixtures (Matches)

Tool	Description
get_fixtures	Get matches by ID, date, league, team, live status, or date range
get_rounds	Get available rounds for a league and season
get_head_to_head	Head-to-head history between two teams
get_fixture_statistics	Match stats (shots, possession, passes, corners, etc.)
get_fixture_events	Match events (goals, cards, substitutions, VAR)
get_fixture_lineups	Starting XI, substitutes, formation, and coach
get_fixture_player_stats	Detailed per-player stats for a match

Standings

Tool	Description
get_standings	League table with points, wins, draws, losses, goals, form

Coaches

Tool	Description
get_coaches	Get coach info by ID, team, or search (includes career history)

Venues

Tool	Description
get_venues	Get stadium info by ID, name, city, country, or search

Transfers

Tool	Description
get_transfers	Transfer history for a player or team

Trophies

Tool	Description
get_trophies	Trophies won by a player or coach

Sidelined

Tool	Description
get_sidelined	Injury/absence history for a player or coach

Injuries

Tool	Description
get_injuries	Current injuries filtered by league, team, player, fixture, or date

Predictions

Tool	Description
get_predictions	Match prediction with win/draw probabilities, advice, and team comparison

Odds

Tool	Description
get_odds	Pre-match betting odds from various bookmakers
get_live_odds	Live/in-play betting odds
get_odds_mapping	List of fixtures with available odds data
get_bookmakers	List or search available bookmakers
get_bet_types	List or search available bet types

Common League IDs

League	ID
Premier League (England)	39
La Liga (Spain)	140
Serie A (Italy)	135
Bundesliga (Germany)	78
Ligue 1 (France)	61
Champions League	2
Europa League	3

Testing

# Run unit tests (mocked, no API calls)
pytest tests/ -v --ignore=tests/test_integration.py

# Run a single test file
pytest tests/test_teams.py -v

# Run a single test
pytest tests/test_teams.py::test_get_teams_by_id -v

# Run integration tests (uses live API, counts against daily limit)
pytest tests/test_integration.py -v

Project Structure

API-Football/
├── server.py           # MCP server entrypoint (FastMCP instance + CLI)
├── api_client.py       # Shared async HTTP client, auth, error handling
├── tools/              # MCP tool modules (one per API domain)
│   ├── __init__.py     # Bulk-registers all tool modules
│   ├── search.py       # Name→ID resolution tools
│   ├── reference.py    # Timezones, countries, seasons, leagues
│   ├── teams.py        # Team info and statistics
│   ├── players.py      # Player info, squads, top scorers/assists/cards
│   ├── fixtures.py     # Matches, H2H, stats, events, lineups
│   ├── standings.py    # League tables
│   ├── coaches.py      # Coach info and career history
│   ├── venues.py       # Stadium info
│   ├── transfers.py    # Transfer history
│   ├── trophies.py     # Player/coach trophies
│   ├── sidelined.py    # Injury/absence history
│   ├── injuries.py     # Current injuries
│   ├── predictions.py  # Match predictions
│   └── odds.py         # Betting odds, bookmakers, bet types
├── tests/              # Test suite
│   ├── conftest.py     # Shared fixtures and mock helpers
│   ├── test_*.py       # Unit tests (mocked)
│   └── test_integration.py  # Live API integration tests
├── .env.example        # Environment variable template
├── Dockerfile          # Container image definition
├── docker-compose.yml  # Docker compose config
├── deploy.sh           # Build + deploy + health-check script
└── requirements.txt    # Python dependencies

License

MIT