World Cup Stats MCP

A read-only MCP server that gives compatible AI clients structured access to a World Cup SQLite database. It supports local stdio development and authenticated Streamable HTTP deployment from the same codebase.

AI host
  └── MCP client
        ├── stdio ── local server process
        └── HTTPS ── remote server on Fly.io
                          └── read-only SQLite

Production scope

For this project, production-ready means a private, single-tenant, read-only service with:

• typed tools and bounded result sizes;

• read-only database access and safe tool errors;

• automated data, protocol and authenticated HTTP tests;

• a health endpoint and structured server logs;

• a pinned, non-root Docker image;

• TLS deployment on Fly.io with a pre-shared bearer token.

This is not an OAuth service for arbitrary third-party users. A public, multi-user MCP product should replace the pre-shared token with a real OAuth authorization server and add its own usage limits and monitoring.

Available tools

• list_tournaments lists available men’s or women’s tournaments.

• get_team_history returns a country’s tournament records and totals.

• get_head_to_head finds World Cup meetings between two countries.

• get_player_record returns appearances, starts, goals and knockout statistics.

All tools are read-only. The server does not expose arbitrary SQL.

Dataset

The project includes the SQLite edition of The Fjelstul World Cup Database:

• 22 men’s tournaments from 1930–2022;

• 8 women’s tournaments from 1991–2019;

• matches, teams, squads, appearances, goals, cards and standings.

Attribution, licence and the exact checksum are in data/README.md. The database and schema are distributed under CC BY-SA 4.0.

Local setup

Requirements:

• Python 3.12 or newer;

• uv;

• Node.js if using MCP Inspector.

Install the locked dependencies:

cd "/Users/lukebyrne/Documents/builds/world-cup-stats-mcp"
uv sync --no-editable

Run all tests:

uv run --no-editable pytest

Run an ordinary Python query before introducing MCP:

uv run --no-editable python scripts/demo_query.py

Test the local stdio server

Launch MCP Inspector:

npx -y @modelcontextprotocol/inspector \
  uv \
  --directory "/Users/lukebyrne/Documents/builds/world-cup-stats-mcp" \
  run \
  --no-editable \
  world-cup-stats-mcp

In Inspector, open Tools, list the tools and call get_player_record with Kylian Mbappe.

The ready-to-use stdio configuration is in mcp.json.

Test Streamable HTTP locally

Create a temporary token and start the HTTP transport:

export MCP_API_TOKEN="$(openssl rand -hex 32)"
export MCP_TRANSPORT="streamable-http"
export MCP_PUBLIC_BASE_URL="http://127.0.0.1:8000"
export MCP_ALLOWED_HOSTS="127.0.0.1:8000,localhost:8000"
uv run --no-editable world-cup-stats-mcp

The endpoints are:

Health: http://127.0.0.1:8000/health
MCP:    http://127.0.0.1:8000/mcp

In Inspector, select Streamable HTTP, enter the MCP URL and paste the token into Bearer Token. An omitted or incorrect token receives HTTP 401.

The repeatable command-line smoke test is:

MCP_SERVER_URL="http://127.0.0.1:8000/mcp" \
MCP_API_TOKEN="$MCP_API_TOKEN" \
uv run --no-editable python scripts/remote_smoke_test.py

Build the container

The Docker image contains the immutable database snapshot and runs as a non-root user:

docker build -t world-cup-stats-mcp .
docker run --rm \
  -p 8000:8000 \
  -e MCP_API_TOKEN="$MCP_API_TOKEN" \
  -e MCP_PUBLIC_BASE_URL="http://127.0.0.1:8000" \
  -e MCP_ALLOWED_HOSTS="127.0.0.1:8000,localhost:8000" \
  world-cup-stats-mcp

Fly can build the same Dockerfile remotely, so a local Docker daemon is not required for deployment.

Deploy to Fly.io

Install and authenticate Fly’s CLI:

brew install flyctl
fly auth login

The repository contains a checked-in fly.toml. Set the bearer token as a Fly secret, then deploy:

fly secrets set MCP_API_TOKEN="$MCP_API_TOKEN"
fly deploy

Check the deployment:

fly status
fly logs
curl --fail "https://world-cup-mcp-luke.fly.dev/health"

Run the authenticated MCP smoke test:

MCP_SERVER_URL="https://world-cup-mcp-luke.fly.dev/mcp" \
MCP_API_TOKEN="$MCP_API_TOKEN" \
uv run --no-editable python scripts/remote_smoke_test.py

Recording prompts

Start with:

Compare Lionel Messi and Kylian Mbappé’s World Cup records through 2022. Include appearances, starts, total goals, knockout goals, final appearances and final goals. Use only the connected World Cup tools.

Then demonstrate a multi-tool question:

Compare Argentina and France at the men’s World Cup since 1990. Include each team’s tournament record and their head-to-head matches, then give me an evidence-based verdict. Use only the connected World Cup tools.

The second prompt should call get_team_history twice and get_head_to_head once.

Data conventions

• Match wins and losses follow the source database’s convention. A knockout match decided on penalties counts as a win for the shootout winner.

• Shootout wins and losses are also returned separately.

• Own goals are excluded from personal goal totals.

• Germany and West Germany remain separate source teams.

• SQLite is opened with mode=ro and PRAGMA query_only.

• Set WORLDCUP_DB_PATH only when moving the database file.