Soccer

You run a Soccer MCP Server to access live and historical football data through an MCP interface. It connects to the API-Football service via RapidAPI, letting you query leagues, teams, players, fixtures, live events, and match analytics from your applications or conversational tools.

How to use

You interact with the Soccer MCP Server through an MCP client or integration. Start the server in your environment, then use the available tools to request data such as league standings, team info, player statistics, fixture details, and live match events. When your client sends a request to the server, it will return structured results you can display in your application, dashboard, or chat workflow.

How to install

Prerequisites: Python installed on your system and Docker installed if you plan to use the Docker option.

# Option A: Direct Python execution
# 1) Clone the project repository
# 2) Install dependencies
# 3) Set your API key environment variable
# 4) Start the server with Python

# Step 1 & 2
# (Commands shown as placeholders for your environment; adapt paths as needed)

# Step 3
export RAPID_API_KEY_FOOTBALL=your_api_key_here

# Step 4
python soccer_server.py

# Optional: start using the MCP runner
mcp run soccer-server.py

# Option B: Run via Docker (recommended for Claude Desktop integration)
# Step 1: Build the Docker image
# docker build -t soccer_server .

# Step 2: Run the container with your API key
docker run -d -p 5000:5000 -e RAPID_API_KEY_FOOTBALL=your_api_key_here --name soccer_server soccer_server

Additional configuration and usage notes

Environment variable for API access is required. The server relies on RAPID_API_KEY_FOOTBALL to authenticate with API-Football via RapidAPI.

For Claude Desktop users, you have two main options to integrate the soccer MCP server into your workflow:

Configuration for Claude Desktop (two options)

Option 1: Using Docker (Recommended) allows you to run the server in a container and reference it from Claude.

{
  "mcpServers": {
    "soccer_server": {
      "command": "docker",
      "args": [
        "run",
        "-d",
        "-p",
        "5000:5000",
        "-e",
        "RAPID_API_KEY_FOOTBALL=your_api_key_here",
        "--name",
        "soccer_server",
        "soccer_server"
      ],
      "env": {
        "RAPID_API_KEY_FOOTBALL": "your_api_key_here"
      }
    }
  }
}

Option 2: Direct Python execution

If you prefer running the server directly with Python, use this minimal configuration and provide the Python path and script path as shown.

{
  "mcpServers": {
    "soccer_server": {
      "command": "/path/to/your/python",
      "args": [
        "/path/to/soccer_server.py"
      ],
      "env": {
        "RAPID_API_KEY_FOOTBALL": "your_api_key_here"
      }
    }
  }
}

Security and best practices

Keep your API key secret. Do not commit the API key into code repositories. Use environment variables or secret management to inject RAPID_API_KEY_FOOTBALL at runtime.

If you run in Docker, ensure the container has network access to the API service and that port 5000 is accessible to your Murray MCP clients.

Troubleshooting and notes

If the server fails to start, verify that the RAPID_API_KEY_FOOTBALL environment variable is set correctly in the chosen startup method. Check that the required dependencies are installed (Python packages via pip) and that the correct Python path or Docker image name is used.

The server exposes a comprehensive set of tools for football data, including league data, player and team information, fixtures, live match data, and match analysis. Use your MCP client to query these tools and handle the responses in your application.

Notes

The server uses API-Football via RapidAPI, validates inputs with Pydantic, and communicates with the API using Requests.

Available tools

get_league_id_by_name

Retrieve the league ID for a given league name.

get_all_leagues_id

Retrieve all league IDs, with optional country filtering.

get_standings

Fetch league standings for specified leagues and seasons.

get_league_info

Get information about a specific league.

get_league_fixtures

Retrieve all fixtures for a league and season.

get_league_schedule_by_date

Get league schedule for specific dates.

get_player_id

Find player IDs and information by player name.

get_player_profile

Retrieve a player's profile by name.

get_player_statistics

Get detailed player statistics by seasons and league.

get_player_statistics_2

Get player statistics by seasons and league ID.

get_team_fixtures

Return past or upcoming fixtures for a team.

get_team_fixtures_by_date_range

Get team fixtures within a date range.

get_team_info

Retrieve basic information about a team.

get_fixture_statistics

Get detailed statistics for a specific fixture.

get_fixture_events

Retrieve all in-game events for a fixture.

get_multiple_fixtures_stats

Fetch statistics for multiple fixtures at once.

get_live_match_for_team

Check if a team is currently playing live.

get_live_stats_for_team

Retrieve live in-game stats for a team in a match.

get_live_match_timeline

Get real-time timeline of events for a live match.