Soccerdata Mcp Server

What is Soccerdata Mcp Server about?

Provides real‑time football data sourced from SoccerDataAPI. It returns structured information such as active match listings, detailed event timelines, team line‑ups, betting odds, and league metadata, all through natural language interactions powered by MCP.

How to use Soccerdata Mcp Server?

1. Install the server via Smithery (recommended):

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

2. Clone the repository and sync dependencies with uv:

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

3. Create a .env file containing your SoccerDataAPI authentication key:

   AUTH_KEY=your_auth_key
   

4. Register the server in your MCP client (e.g., Claude Desktop) by adding an entry to the client’s claude_desktop_config.json that points to the Python executable (uv run server.py) and loads the .env file.
5. Query the server using the exposed get_livescores() tool or any natural‑language prompt like:
   • "What football matches are being played right now?"
   • "Show me the line‑up for PSG vs Aston Villa today."

Key Features of Soccerdata Mcp Server

• Live Match Listings – Global view of all currently active games with kickoff times, stadiums, and scores.
• Match Details – Status, half‑time/full‑time scores, extra‑time and penalty results.
• Event Stream – Goals, substitutions, yellow/red cards, and penalties with timestamps.
• Team Line‑ups – Starting XI, bench, injury status, and formation.
• Betting Odds – Win/draw/lose, over/under, and handicap odds.
• League Metadata – League name, country, and competition format.
• Focused Scope – Only live, upcoming, and recently finished matches are covered.

Use Cases of Soccerdata Mcp Server

• Sports Chatbots – Enable conversational assistants to answer real‑time football queries.
• Betting Platforms – Pull live odds and match events for betting dashboards.
• Media & Publishing – Auto‑generate match summaries and statistics for articles.
• Fan Apps – Provide supporters with instant access to scores, line‑ups, and key events.
• Data Analytics – Feed live match data into analytics pipelines for performance tracking.

FAQ from the Soccerdata Mcp Server

Q: Which programming language is required? A: Python 3.12+ with the uv package manager.

Q: Do I need a paid SoccerDataAPI account? A: Yes, an API key from https://soccerdataapi.com/ is required.

Q: Can I run the server locally? A: Absolutely. Clone the repo, set the .env file, and start the server with uv run server.py.

Q: Is there a Docker image? A: Not provided in the repository; you can containerize the Python app yourself.

Q: How do I expose the server to remote MCP clients? A: Ensure the host machine’s network allows inbound connections on the port the server listens to (default configured in server.py).

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