Soccer MCP Server for Football Data Integration

Overview

The Soccer MCP Server is a Python-based implementation of the Model Context Protocol (MCP) designed to provide access to football (soccer) statistics and live match data using the API-Football service. It acts as a bridge between applications and football data services, offering comprehensive data for leagues, teams, and players worldwide.

Features

• League Data: Access standings, fixtures, and schedules for various leagues.
• Team Information: Retrieve team details and fixtures.
• Player Statistics: Get profiles and detailed statistics for players.
• Live Match Data: Access real-time match events, statistics, and timelines.
• Match Analysis: Analyze match statistics and events.

Configuration

To use the Soccer MCP Server, you need 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:
   bash 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.
• get_all_leagues_id: Retrieve a list of all football leagues with IDs.
• get_standings: Retrieve league standings for multiple leagues and seasons.
• get_league_info: Retrieve information about a specific football league.
• get_league_fixtures: Retrieve all fixtures for a given league and season.
• get_league_schedule_by_date: Retrieve the schedule for a league on specified dates.

Player Data

• get_player_id: Retrieve player IDs and information for players matching a name.
• get_player_profile: Retrieve a player's profile by their last name.
• get_player_statistics: Retrieve detailed player statistics by seasons and league name.
• get_player_statistics_2: Retrieve detailed player statistics by seasons and league ID.

Team Data

• get_team_fixtures: Returns past or upcoming fixtures for a team.
• get_team_fixtures_by_date_range: Retrieve fixtures for a team within a date range.
• get_team_info: Retrieve basic information about a specific team.

Match/Fixture Data

• get_fixture_statistics: Retrieves detailed statistics for a specific fixture.
• get_fixture_events: Retrieves all in-game events for a fixture.
• get_multiple_fixtures_stats: Retrieves statistics for multiple fixtures at once.

Live Match Data

• get_live_match_for_team: Checks if a team is currently playing live.
• get_live_stats_for_team: Retrieves live in-game stats for a team in a match.
• get_live_match_timeline: Retrieves real-time timeline of events for a team's live match.

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

Option 1: Using Docker (Recommended)

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

2. Install dependencies:
   bash pip install -r requirements.txt

3. Build the Docker image:
   bash docker build -t soccer_server .

4. Run the Docker container (ensure your API key is passed as an environment variable):
   bash docker run -d -p 5000:5000 -e RAPID_API_KEY_FOOTBALL=your_api_key_here --name soccer_server soccer_server

5. Add this to your claude_desktop_config.json:
   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:
   bash git clone https://github.com/obinopaul/soccer-mcp-server.git cd soccer-mcp-server

2. Install dependencies:
   bash pip install -r requirements.txt

3. Set the API key environment variable:
   bash export RAPID_API_KEY_FOOTBALL=your_api_key_here

4. Add this to your claude_desktop_config.json, adjusting the Python path as needed:
   json { "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.

About

Mirror of https://github.com/obinopaul/soccer-mcp-server