Overview

Feyod MCP Server is a Model Context Protocol (MCP) server focused on match-level analysis for Feyenoord football matches. It exposes structured “tools” — endpoints that provide match statistics, timelines, tactical summaries and real-time event feeds — so language models or downstream applications can request and incorporate detailed match context into responses and workflows.

Designed for developers building analytics dashboards, chat assistants, or automated reporting pipelines, the server bridges raw match data and higher-level interpretations. Instead of embedding bulky data directly into a model prompt, clients can query the MCP server for focused information (for example: “goals and expected goals (xG) timeline”, “player heatmaps”, or “substitution impact”) and use those results to produce concise, accurate outputs.

Features

Lightweight MCP-compliant HTTP API exposing a catalog of match analysis tools
Match-level statistics: scores, xG, possession, passing accuracy, set pieces
Tactical insights: formations, pressing intensity, player roles and heatmaps
Timeline and event feed (minute-by-minute events, timestamps, event types)
Real-time mode with optional WebSocket feed for live matches
Pluggable data provider configuration (file, HTTP provider, or database)
Docker-ready for simple deployment and environment-driven configuration

Installation / Configuration

Prerequisites: Node.js 16+ and npm, or Docker.

Clone the repo and install dependencies:

git clone https://github.com/jeroenvdmeer/feyod-mcp.git
cd feyod-mcp
npm install

Copy and edit the example environment file:

cp .env.example .env
# Edit .env to set DATA_PROVIDER_URL, DATA_PROVIDER_KEY, PORT, etc.

Common .env variables:

PORT=3000
MCP_BIND=0.0.0.0
DATA_PROVIDER_URL=https://api.example-data-provider.com
DATA_PROVIDER_KEY=your_api_key_here
DATABASE_URL=postgres://user:pass@db:5432/feyod
CACHE_TTL=60        # seconds
LOG_LEVEL=info

Run the server in development mode:

npm run dev
# or for production
npm run start

Docker (optional):

Dockerfile and docker-compose.yml are provided. Example:

docker build -t feyod-mcp .
docker run -p 3000:3000 --env-file .env feyod-mcp

Available Tools / Resources

The server exposes a set of tools that map to useful match queries. Each tool is invokable via HTTP and returns JSON suitable for injection into model context.

Tool catalog (examples):

match-stats — summary metrics for a match (score, xG, possession, shots)
timeline — minute-by-minute event timeline (goals, cards, substitutions)
tactical-insights — formation, pressing lines, compactness, player roles
player-comparison — head-to-head stats between two players
live-feed — WebSocket feed for real-time events
heatmap — per-player positional density map

API endpoints overview:

Endpoint	Method	Purpose
/tools	GET	List available tools and schemas
/tool/:name	POST	Invoke a tool with JSON parameters
/matches/:id	GET	Raw match metadata and source links
/ws	WebSocket	Subscribe to real-time events for a match

Example: list tools

curl http://localhost:3000/tools

Invoke match-stats:

curl -X POST http://localhost:3000/tool/match-stats \
  -H "Content-Type: application/json" \
  -d '{"matchId":"2025-04-12-FEY-UTR"}'

Sample response (abbreviated):

{
  "matchId": "2025-04-12-FEY-UTR",
  "score": {"home": 2, "away": 1},
  "xg": {"home": 1.9, "away": 1.2},
  "possession": {"home": 58, "away": 42},
  "shots": {"home": 14, "away": 10}
}

Use Cases

Post-match reporting: Generate automated match summaries for social media or newsletters by invoking match-stats, timeline, and tactical-insights, then feeding the combined data to a language model to draft copy.
Live commentary assistant: Subscribe to /ws for real-time events and use the timeline and player-comparison tools to provide instant context during a broadcast (e.g., “This is Player X’s third successful through ball today; season average is 0.8 per match”).
Tactical analysis dashboard: Query tactical-insights and heatmap tools to render formation diagrams and press maps for coaching staff or analysts.
Scouting and player comparison: Use player-comparison and aggregated match-stats across multiple matches to highlight strengths and weaknesses of targets.
Fan applications and chatbots: Embed tool responses into chat workflows so fans can ask natural-language questions like “How did Feyenoord create the second goal?” and receive answers based on structured events and tactical summaries.

Integration Tips and Troubleshooting

Model integration: Use GET /tools to discover tool parameter schemas. For LLMs with tool-call capabilities, register each tool with its input/output schema so the model can decide when to call them.
Caching: Set CACHE_TTL for frequently requested matches to reduce provider load.
Data freshness: For live matches, enable the WebSocket feed and set a short polling interval for stat endpoints that rely on aggregated calculations.
Logging: Increase LOG_LEVEL to debug if tool invocations fail; check connectivity to DATA_PROVIDER_URL and DATABASE_URL.
Error responses: Tool errors return HTTP 4xx/5xx with a JSON body { “error”: “…”, “details”: … }.

For the full source, examples and advanced configuration (auth, custom data adapters), see the repository: https://github.com/jeroenvdmeer/feyod-mcp

Feyod MCP Server: Feyenoord Match Analysis