MCP Soccer Data

🚀 🏈 Soccer Data MCP Server

MCP-Soccerdata is an open - source server that connects to SoccerDataAPI, providing the latest football match information and enabling data queries through natural - language interaction.

• MCP-Soccerdata is an open - source Model Context Protocol (MCP) server that connects to SoccerDataAPI. It offers the latest football match information and enables data queries through natural - language interaction.
• Designed to work with MCP - enabled clients (e.g., Claude Desktop), it allows users to retrieve football data via large language models (LLMs).

✨ Features

🏟️ Real - time Football Match Insights

MCP-Soccerdata focuses on providing real - time information on ongoing football matches worldwide.

"Which football matches are currently taking place?" "Tell me the expected starting lineup for Paris Saint - Germain vs. Aston Villa today." "Please inform me of the scores and number of goals in the recently finished matches."

→ It provides structured relevant information, including the following detailed categories.

- Match List and Basic Information

• A list of all matches being held globally
• Names of the home and away teams
• Kick - off time and match date
• Information about the match venue
• Current score

- Match Details

• Match status: scheduled, in progress, or completed
• Goal breakdown: first half, second half, extra time, penalty shoot - out
• Final result: win, draw, or loss

- Key Match Events

• Goal details (who scored, time, method)
• Substitutions
• Yellow and red cards
• Penalty decisions

- Team Line - ups

• Starting XI list
• Information about substitute players
• Injury status
• Formation arrangement

- Odds and Betting Information

• Odds for win, draw, and loss
• Over/under odds for the number of goals
• Asian handicap odds for the score

- League Metadata

• League name
• Country
• Competition format (e.g., regular season, knockout stage)

⚠️ Focus on real - time, upcoming, and recently finished matches.

🎥 Demo

🚀 Quick Start

Installation via Smithery

To automatically install the Amadeus MCP server for Claude Desktop via Smithery:

npx -y @smithery/cli install @yeonupark/mcp-soccer-data --client claude

Prerequisites

• Python 3.12+
• uv package manager
• A Soccerdata API account
• An MCP - enabled client (e.g., Claude Desktop)

Manual Installation Guide

1. Clone the repository:

   git clone https://github.com/yeonupark/mcp-soccer-data.git
   cd mcp-soccer-data
   

2. Install the dependencies:

   pip install -r requirements.txt
   

3. Set up environment variables: Create a .env file and add the following content:

   API_KEY=your_api_key_here
   

4. Run the server:

   python server.py
   

Configure the MCP Client

1. Open the client's configuration interface.
2. Add the following settings:
   • Name: MCP-Soccerdata
   • Type: football_data
   • Address: http://localhost:5000

💻 Usage Examples

Basic Usage

print(get_livescores())

Example output:

[
  {
    "home_team": "Paris Saint - Germain",
    "away_team": "Marseille",
    "score": "2-1",
    "status": "finished"
  },
  {
    "home_team": "Bayern Munich",
    "away_team": "Borussia Dortmund",
    "score": "3-0",
    "status": "in_progress"
  }
]

📄 License

This project is licensed under the MIT License.