Soccer MCP Server exposes a Python-based MCP interface to access football data via the API-Football service. It provides a rich set of tools for league data, team information, player statistics, and live match data, including events and timelines. You can query league standings, fixtures, schedules, and aggregate statistics for teams and players, as well as retrieve real-time live match information when available. The server is designed to be used with Claude Desktop or any MCP-compatible client that can interact with the MCP endpoints exposed by the server.

To use the tools, ensure you have a RapidAPI API key for API-Football and set RAPID_API_KEY_FOOTBALL in your environment. Start the server (for example: python soccer_server.py) and connect via your MCP client. The provided toolset includes: get_league_id_by_name, get_all_leagues_id, get_standings, get_league_info, get_league_fixtures, get_league_schedule_by_date, get_player_id, get_player_profile, get_player_statistics, get_player_statistics_2, get_team_fixtures, get_team_ffixtures_by_date_range, get_team_info, get_fixture_statistics, get_fixture_events, get_multiple_fixtures_stats, get_live_match_for_team, get_live_stats_for_team, and get_live_match_timeline. Each tool is designed to fetch specific data from API-Football, enabling comprehensive football analytics and live data access within your conversations.

Prerequisites:

• Python 3.8+ installed on your system
• Access to the internet to install dependencies
• A RapidAPI API key for the API-Football service (set RAPID_API_KEY_FOOTBALL)

Step-by-step installation:

1. Clone the repository: git clone https://github.com/obinopaul/soccer-mcp-server.git cd soccer-mcp-server

2. Create and activate a virtual environment (optional but recommended): python -m venv venv

   On Windows

   venv\Scripts\activate

   On macOS/Linux

   source venv/bin/activate

3. Install dependencies from requirements.txt: pip install -r requirements.txt

4. Set your API key in the environment (example for Unix-like systems): export RAPID_API_KEY_FOOTBALL=your_api_key_here

   On Windows (PowerShell)

   $env:RAPID_API_KEY_FOOTBALL="your_api_key_here"

5. Run the server: python soccer_server.py

   Alternatively, if you prefer using the MCP command alias

   mcp run soccer-server.py

6. (Optional) If integrating with Claude Desktop via Docker:

   • Build the image and run the container with the environment variable RAPID_API_KEY_FOOTBALL set, then use the provided configuration in claude_desktop_config.json as shown in the README.

Notes & tips:

• The server relies on API-Football via RapidAPI; ensure your RAPID_API_KEY_FOOTBALL is valid and has access to the API-Football endpoints.
• The timeout for network calls is configured for reliability; if you experience delays, verify network connectivity and API rate limits.
• When using Docker, pass the RAPID_API_KEY_FOOTBALL environment variable to the container to avoid authentication errors.
• If you modify the server code, ensure dependencies are reinstalled (pip install -r requirements.txt) and restart the server.
• The tools rely on unique IDs (league_id, fixture_id, etc.). Use get_league_id_by_name or get_player_id first to discover IDs before deeper lookups.
• For Claude Desktop integration, ensure the json configuration in claude_desktop_config.json points to the correct python path and script, and that environment variables are properly exposed to the running process.