SoccerDataAPI

What is mcp-soccer-data?

mcp-soccer-data is an open-source Model Context Protocol (MCP) server that provides real-time football match data based on the SoccerDataAPI. It enables users to retrieve football data by leveraging large language models (LLMs) through MCP-enabled clients like Claude Desktop.

How to use mcp-soccer-data?

To use mcp-soccer-data, you need Python 3.12+, the uv package manager, a Soccerdata API account, and an MCP-compatible client (e.g., Claude for Desktop).

1. Install via Smithery (for Claude Desktop):

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

2. Manual Setup:
   • Clone the repository: git clone https://github.com/yeonupark/mcp-soccer-data.git and cd mcp-soccer-data
   • Install dependencies: uv sync
   • Get your API key from https://soccerdataapi.com/ and set it in a .env file: AUTH_KEY=your_auth_key
   • Configure your MCP client (e.g., Claude for Desktop) by adding the server configuration to ~/Library/Application Support/Claude/claude_desktop_config.json.

Once set up, you can interact with the server using natural language queries through your MCP client.

Key Features of mcp-soccer-data

• Live Football Match Insights: Delivers real-time information about ongoing football matches globally.
• Match Listings & Basic Info: Provides details like active matches, team names, kickoff times, stadium details, and current scores.
• Match Details: Includes match status (scheduled, in progress, finished), goal breakdown, and final results.
• Key Match Events: Tracks goal events, substitutions, cards (yellow/red), and penalties.
• Team Lineups: Offers starting XI, bench players, injury status, and team formation.
• Odds & Betting Information: Provides Win/Draw/Lose, Over/Under, and Handicap betting odds.
• League Metadata: Includes league name, country, and competition format.
• Focused Data: Exclusively focuses on live, upcoming, and recently finished matches.
• get_livescores() tool: Exposes a tool to MCP clients for retrieving real-time football match information.

Use Cases of mcp-soccer-data

• Real-time Sports Updates: Users can get instant updates on ongoing football matches.
• Sports Betting Analysis: Access to odds and match details can aid in betting decisions.
• Football Research: Quickly retrieve historical and current match data for analysis.
• Integration with LLMs: Enables natural language interaction with football data through MCP-compatible clients.

FAQ about mcp-soccer-data

Q: What kind of football data does mcp-soccer-data provide? A: It provides real-time information on live, upcoming, and recently finished matches, including scores, lineups, events, odds, and league metadata.

Q: What are the prerequisites for using mcp-soccer-data? A: You need Python 3.12+, uv package manager, a Soccerdata API account, and an MCP-compatible client like Claude for Desktop.

Q: Can I get historical match data? A: No, the project is focused exclusively on live, upcoming, and recently finished matches.

Q: How do I get an API key for SoccerdataAPI? A: You can sign up and obtain your API key from https://soccerdataapi.com/.

Q: What is an MCP server? A: An MCP (Model Context Protocol) server allows large language models (LLMs) to interact with external data sources and tools, enabling them to provide more accurate and up-to-date information.

⚽️ Soccerdata MCP Server

• MCP-Soccerdata is an open-source Model Context Protocol (MCP) server that connects to the SoccerDataAPI to deliver up-to-date football match information via natural language interactions.

• Designed for use with MCP-enabled clients such as Claude Desktop, it allows users to retrieve football data by leveraging large language models (LLMs).

---

✨ Features

🏟️ Live Football Match Insights

MCP-Soccerdata focuses on delivering real-time information about ongoing football matches around the world.

"What football matches are being played right now?"
"What are the predicted lineups for PSG vs Aston Villa today?"
"Please tell me the scores and number of goals from recent football matches."

→ Provides relevant football data in a structured format, including the detailed categories described below.

- Match Listings & Basic Info

• Global list of all currently active matches
• Home and away team names
• Kickoff time and match date
• Stadium details
• Current score

- Match Details

• Match status: scheduled, in progress, or finished
• Goal breakdown: first half, second half, extra time, penalty shootout
• Final result: win, draw, or loss

- Key Match Events

• Goal events (who scored, when, how)
• Substitutions
• Yellow and red cards
• Penalties

- Team Lineups

• Starting XI
• Bench players
• Injury status
• Team formation

- Odds & Betting Information

• Win / Draw / Lose odds
• Over / Under odds
• Handicap betting odds

- League Metadata

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

⚠️ Focused exclusively on live, upcoming, and recently finished matches

---

🎥 Demo

---

🚀 Quick Start

Installing via Smithery

To install Amadeus MCP Server for Claude Desktop automatically via Smithery:

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

Prerequisites

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

1. Clone and Setup

• Clone the repository

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

• Install dependencies

uv sync

2. Get Your API Key and Set Environment

• Create a .env file with your credentials:

AUTH_KEY=your_auth_key

Sign up on https://soccerdataapi.com/ and get your own Auth keys.

3. Configure MCP Client

• Register this server in your MCP client (e.g., Claude for Desktop).

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
      "mcp-soccer-data": {
          "command": "/ABSOLUTE/PATH/TO/PARENT/FOLDER/uv",
          "args": [
              "--directory",
              "/ABSOLUTE/PATH/TO/PARENT/FOLDER/src/",
              "run",
              "--env-file",
              "/ABSOLUTE/PATH/TO/PARENT/FOLDER/.env",
              "server.py"
          ]
      }
  }
}

---

🛠️ Tools

The follwing tool is exposed to MCP clients:

get_livescores()

-> Returns real-time information about ongoing football matches around the world.

---

📝 License

• This project is licensed under the MIT License. See the LICENSE file for details.
• Built with Model Context Protocol