⚽️ 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