Query Live Soccer Data via Natural Language
An MCP server delivering live football match data - scores, lineups, events, and odds - for live, upcoming, and recently finished matches.
Why it matters
Access real-time football match data, including live scores, lineups, and betting odds, by querying the SoccerDataAPI using natural language. This asset provides a bridge for applications to interact with live sports information.
Outcomes
What it gets done
Retrieve live scores and match details for ongoing football games.
Fetch predicted team lineups and player information.
Access betting odds and historical match data.
Integrate live sports data into applications through natural language queries.
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/vb-soccerdataapi | bash Capabilities
Tools your agent gets
Returns real-time information about current football matches worldwide
Overview
SoccerDataAPI MCP Server
This MCP server exposes a get_livescores tool returning real-time football match data: scores, status, goal events, lineups, betting odds, and league metadata, scoped to live, upcoming, and recently finished matches only. Use it for real-time football match queries through an MCP client like Claude Desktop. Not for historical archives or season-long statistics.
What it does
An MCP server connecting to SoccerDataAPI to deliver live football match information through natural language, exposing a single tool, get_livescores(), that returns real-time data on ongoing matches worldwide. That data spans match listings and basic info (active matches, home and away teams, kickoff time and date, stadium details, current score), match details (status as scheduled, in progress, or finished, a goal breakdown by first half, second half, extra time, and penalty shootout, and the final result of win, draw, or loss), key match events (goal events with who scored and when and how, substitutions, yellow and red cards, and penalties), team lineups (starting XI, bench players, injury status, and team formation), odds and betting information (win/draw/lose odds, over/under odds, and handicap betting odds), and league metadata (league name, country, and competition format such as regular season or knockout stage). It is explicitly scoped to live, upcoming, and recently finished matches only - not historical archives or season-long statistics.
When to use - and when NOT to
Use it for questions like "what football matches are being played right now," "what are the predicted lineups for PSG vs Aston Villa today," or "tell me the scores and number of goals from recent football matches" - real-time football data delivered via an MCP-enabled client such as Claude Desktop. It is not for historical match archives, season-long statistics, or any football data outside the live, upcoming, or recently-finished window this server is scoped to.
Capabilities
The single exposed tool, get_livescores(), takes no parameters and returns one payload per call covering every currently live, upcoming, and recently finished match worldwide - there is no separate tool or parameter for filtering by team, league, or date; narrowing to a specific match happens by reading the returned payload rather than by request parameters.
How to install
npx -y @smithery/cli install @yeonupark/mcp-soccer-data --client claude
Or manually: clone the repository, run uv sync to install dependencies (Python 3.12+ and the uv package manager are required), create a .env file with AUTH_KEY set to a key obtained by signing up at soccerdataapi.com, then register the server in Claude Desktop's config at ~/Library/Application Support/Claude/claude_desktop_config.json, pointing uv at the src/ directory with --env-file set to the local .env and running server.py.
Who it's for
Football fans and developers building sports-data assistants who want live scores, lineups, match events, and betting odds available conversationally, without building a direct SoccerDataAPI integration themselves. It requires an MCP-compatible client such as Claude for Desktop, and its own security posture has been reviewed under the MseeP.ai security assessment program, with results published alongside the project.
Source README
⚽️ 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+
uvpackage 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
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.