Glama
Sign In

Soccer MCP Server

by obinopaul
Verified
GitHub
Python
RedditDiscord
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Integrations

  • Supports containerized deployment using Docker for easier setup and configuration of the soccer data server

  • Provides access to Premier League data including standings, fixtures, schedules, team information, and match statistics

  • Uses Pydantic for input validation of football data requests and responses

Soccer MCP Server

A Python server implementing Model Context Protocol (MCP) for football (soccer) statistics and live match data using the API-Football service.

Overview

This server provides a comprehensive set of tools for accessing football data through the API-Football API. It serves as a bridge between applications and football data services, offering both live match information and historical statistics for leagues, teams, and players worldwide.

Features

  • League data (standings, fixtures, schedules)
  • Team information and fixtures
  • Player statistics and profiles
  • Live match data (events, statistics, timelines)
  • Match analysis (statistics, events)

Configuration

This server requires an API key from RapidAPI for the API-Football service:

  1. Create an account on RapidAPI
  2. Subscribe to the API-Football API
  3. Set the environment variable:
    RAPID_API_KEY_FOOTBALL=your_api_key_here

Tools

League Data

  • get_league_id_by_name
    • Retrieve the league ID for a given league name
    • Example: get_league_id_by_name(league_name="Premier League")
  • get_all_leagues_id
    • Retrieve a list of all football leagues with IDs
    • Can be filtered by country
    • Example: get_all_leagues_id(country=["England", "Spain"])
  • get_standings
    • Retrieve league standings for multiple leagues and seasons
    • Can be filtered by team
    • Example: get_standings(league_id=[39, 140], season=[2022, 2023])
  • get_league_info
    • Retrieve information about a specific football league
    • Example: get_league_info(league_name="Champions League")
  • get_league_fixtures
    • Retrieves all fixtures for a given league and season
    • Example: get_league_fixtures(league_id=39, season=2023)
  • get_league_schedule_by_date
    • Retrieves the schedule for a league on specified dates
    • Example: get_league_schedule_by_date(league_name="Premier League", date=["2024-03-08", "2024-03-09"], season="2023")

Player Data

  • get_player_id
    • Retrieve player IDs and information for players matching a name
    • Example: get_player_id(player_name="Messi")
  • get_player_profile
    • Retrieve a player's profile by their last name
    • Example: get_player_profile(player_name="Messi")
  • get_player_statistics
    • Retrieve detailed player statistics by seasons and league name
    • Example: get_player_statistics(player_id=154, seasons=[2022, 2023], league_name="La Liga")
  • get_player_statistics_2
    • Retrieve detailed player statistics by seasons and league ID
    • Example: get_player_statistics_2(player_id=154, seasons=[2022, 2023], league_id=140)

Team Data

  • get_team_fixtures
    • Returns past or upcoming fixtures for a team
    • Example: get_team_fixtures(team_name="Manchester United", type="past", limit=3)
  • get_team_fixtures_by_date_range
    • Retrieve fixtures for a team within a date range
    • Example: get_team_fixtures_by_date_range(team_name="Liverpool", from_date="2023-09-01", to_date="2023-09-30", season="2023")
  • get_team_info
    • Retrieve basic information about a specific team
    • Example: get_team_info(team_name="Real Madrid")

Match/Fixture Data

  • get_fixture_statistics
    • Retrieves detailed statistics for a specific fixture
    • Example: get_fixture_statistics(fixture_id=867946)
  • get_fixture_events
    • Retrieves all in-game events for a fixture (goals, cards, subs)
    • Example: get_fixture_events(fixture_id=867946)
  • get_multiple_fixtures_stats
    • Retrieves statistics for multiple fixtures at once
    • Example: get_multiple_fixtures_stats(fixture_ids=[867946, 867947, 867948])

Live Match Data

  • get_live_match_for_team
    • Checks if a team is currently playing live
    • Example: get_live_match_for_team(team_name="Chelsea")
  • get_live_stats_for_team
    • Retrieves live in-game stats for a team in a match
    • Example: get_live_stats_for_team(team_name="Liverpool")
  • get_live_match_timeline
    • Retrieves real-time timeline of events for a team's live match
    • Example: get_live_match_timeline(team_name="Manchester City")

Usage

The server is implemented using the Fast MCP framework and can be run as a standalone service.

# Start the server python soccer_server.py # or mcp run soccer-server.py

Configuration

  • The server runs with a 30-second timeout for more reliable operation
  • Signal handlers are implemented for graceful shutdown (Ctrl+C)

Usage with Claude Desktop

  1. Clone this repository
git clone https://github.com/obinopaul/soccer-mcp-server.git cd soccer-mcp-server
  1. Install dependencies
pip install -r requirements.txt
  1. Build the Docker image
docker build -t soccer_server .
  1. Run the Docker container (ensure your API key is passed as an environment variable)
docker run -d -p 5000:5000 -e RAPID_API_KEY_FOOTBALL=your_api_key_here --name soccer_server soccer_server
  1. Add this to your claude_desktop_config.json:
{ "mcpServers": { "soccer_server": { "command": "docker", "args": [ "exec", "-i", "soccer_server", "python", "soccer_server.py" ], "env": { "RAPID_API_KEY_FOOTBALL": "your_api_key_here" } } } }

Option 2: Direct Python Execution

  1. Clone this repository
git clone https://github.com/obinopaul/soccer-mcp-server.git cd soccer-mcp-server
  1. Install dependencies
pip install -r requirements.txt
  1. Set the API key environment variable
export RAPID_API_KEY_FOOTBALL=your_api_key_here
  1. Add this to your claude_desktop_config.json, adjusting the Python path as needed:
{ "mcpServers": { "soccer_server": { "command": "/path/to/your/python", "args": [ "/path/to/soccer_server.py" ], "env": { "RAPID_API_KEY_FOOTBALL": "your_api_key_here" } } } }

After adding your chosen configuration, restart Claude Desktop to load the soccer server. You'll then be able to use all the football data tools in your conversations with Claude.

Technical Details

The server is built on:

  • API-Football via RapidAPI
  • MCP for API interface
  • Pydantic for input validation
  • Requests for API communication

License

This MCP server is available under the MIT License.

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

Provides programmatic access to comprehensive football statistics and live match data via API-Football, enabling applications to retrieve league standings, team fixtures, player statistics, and real-time match events.

  1. Overview
    1. Features
      1. Configuration
        1. Tools
          1. League Data
          2. Player Data
          3. Team Data
          4. Match/Fixture Data
          5. Live Match Data
        2. Usage
          1. Configuration
          2. Usage with Claude Desktop
        3. Technical Details
          1. License