SoccerDataAPI Live Match Data MCP Server

Overview

SoccerDataAPI Live Match Data MCP Server streams real-time football match data and exposes it via the Model Context Protocol (MCP). It sits between the SoccerDataAPI (or other live-data sources) and downstream consumers — such as dashboards, bots, or AI models — translating live events, scores, and match metadata into a consistent, subscribable context feed.

This server is useful when you need continuous, low-latency match context for apps that consume streaming data: live score widgets, automated match narrators, in-game analytics, or model-driven assistants that require up-to-the-second game state. It provides connection patterns commonly used by developer workflows (server-sent events / EventSource, webhooks, or programmatic subscriptions), and is intended to be integrated into dashboards or ML pipelines with minimal glue code.

Features

• Streams live match state (scores, events, lineups, statuses) via MCP-compatible endpoints
• Subscribe to one or many match feeds and receive incremental updates
• Bridge between SoccerDataAPI and downstream clients, normalizing event structures
• Lightweight HTTP endpoints for health, management, and subscription control
• Docker-ready and configurable with environment variables or config files
• Simple client examples for SSE and Webhook-style integrations

Installation / Configuration

Prerequisites:

• Docker (recommended) or Node.js (if running locally)
• A SoccerDataAPI key (or configured upstream data source)

Clone the repository and create an environment file:

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

Example .env (adjust values for your environment):

# .env
SOCCERDATA_API_KEY=your_real_api_key_here
MCP_PORT=8080
LOG_LEVEL=info
UPSTREAM_POLL_INTERVAL_MS=5000
DEFAULT_MATCH_IDS=12345,67890

Run with Docker:

# build
docker build -t mcp-soccer-data .

# run (exposes port 8080 by default)
docker run --env-file .env -p 8080:8080 mcp-soccer-data

Run locally with Node.js (if supported by the repo):

npm install
npm start
# or
NODE_ENV=production node ./dist/server.js

Or use Docker Compose (example):

version: '3.8'
services:
  mcp-soccer-data:
    image: mcp-soccer-data:latest
    build: .
    ports:
      - "8080:8080"
    env_file:
      - .env

Configuration notes:

• SOCCERDATA_API_KEY: required to retrieve live data from SoccerDataAPI.
• MCP_PORT: HTTP port for MCP endpoints.
• UPSTREAM_POLL_INTERVAL_MS: controls how often the server queries upstream (if polling).
• DEFAULT_MATCH_IDS: optional CSV list of match IDs to pre-subscribe.

Available Resources

Common endpoints (defaults — confirm exact routes in repository):

Example: stream a match via SSE (curl)

curl -N -H "Accept: text/event-stream" "http://localhost:8080/mcp/stream?matchId=12345&apiKey=your_key"

JavaScript EventSource client:

const url = 'http://localhost:8080/mcp/stream?matchId=12345&apiKey=your_key';
const es = new EventSource(url);

es.onmessage = (e) => {
  const data = JSON.parse(e.data);
  console.log('MCP update', data);
};

es.onerror = (err) => {
  console.error('EventSource error', err);
};

Webhooks: register a webhook URL to receive JSON POSTs when significant events occur (goals, red cards, match start/end).

Use Cases

• Live scoreboard widget

  • Subscribe to /mcp/stream for one or more match IDs.
  • Map incoming score and time fields into UI components to display live scores and last event.

• AI match summarizer or assistant

  • Feed MCP event stream into a conversational model as context (e.g., append events to conversation context).
  • Generate rolling match summaries, highlight reels, or real-time commentary based on structured events.

• Alerts & notifications

  • Register a webhook to receive push notifications on high-priority events (goal, penalty, red card).
  • Use as trigger for push notifications, chat messages, or automated social media posts.

• Analytics pipeline

  • Persist MCP event stream to a time-series store for post-game analysis and model training.
  • Combine live event context with telemetry (possession, xG) for richer insights.

Tips and Next Steps

• Check the repository README and code to confirm exact routes and configuration schema.
• Use Docker for predictable deployment across environments.
• Normalize and validate upstream event payloads before feeding into AI models to reduce prompt noise.
• Add retry/backoff logic for clients connecting to SSE endpoints or webhooks to handle transient upstream disruptions.

Repository and source code: https://github.com/yeonupark/mcp-soccer-data

For SoccerDataAPI-specific documentation or API limits, consult your SoccerDataAPI provider documentation and ensure your key and rate limits are respected when subscribing to many matches.