world-cup-stats-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@world-cup-stats-mcp What's the head-to-head record between Brazil and Germany?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 SQLiteProduction 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.
Related MCP server: World Cup History MCP
Available tools
list_tournamentslists available men’s or women’s tournaments.get_team_historyreturns a country’s tournament records and totals.get_head_to_headfinds World Cup meetings between two countries.get_player_recordreturns 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-editableRun all tests:
uv run --no-editable pytestRun an ordinary Python query before introducing MCP:
uv run --no-editable python scripts/demo_query.pyTest 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-mcpIn 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-mcpThe endpoints are:
Health: http://127.0.0.1:8000/health
MCP: http://127.0.0.1:8000/mcpIn 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.pyBuild 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-mcpFly 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 loginThe 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 deployCheck 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.pyRecording 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=roandPRAGMA query_only.Set
WORLDCUP_DB_PATHonly when moving the database file.
Available Tools
4 toolsget_head_to_headB
Find every World Cup meeting between two countries and aggregate the results.
Inputs: team_a (required), team_b (required), gender, to_year, +1 more. Returns: The complete result returned by the get_head_to_head tool.
get_player_recordB
Get a player's appearances, starts, goals, and knockout record by tournament.
Inputs: player (required), gender, to_year, from_year. Returns: The complete result returned by the get_player_record tool.
get_team_historyC
Get a country's tournament-by-tournament record and aggregate World Cup totals.
Inputs: team (required), gender, to_year, from_year. Returns: The complete result returned by the get_team_history tool.
list_tournamentsC
List the World Cup tournaments available in the local database.
Inputs: gender. Returns: The complete result returned by the list_tournaments tool.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: listing tournaments, team history, head-to-head matchups, and player records. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern (list_tournaments, get_team_history, get_head_to_head, get_player_record), using 'get' for data retrieval and 'list' for enumeration.
With 4 tools, the server is slightly under-scoped for a World Cup stats domain, but each tool covers a meaningful query. The count is reasonable and not problematic.
The tool surface covers team history, head-to-head, and player records, but lacks individual match details or tournament standings, which are notable gaps for a stats MCP.
Maintenance
Related MCP Connectors
UN FAOSTAT global food & agriculture statistics over a local SQLite mirror, via MCP.
Football-Data.org MCP — soccer competitions, matches, standings
API-Football MCP — comprehensive soccer/football data
Unofficial SportsDataIO MCP — wraps SportsDataIO's Big-Six sports data API (sportsdata.io)
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server for FIFA World Cup 2026 data: matches, teams, venues, city guides, fan zones, visa info, injuries, odds, standings, bracket, and historical matchups. 18 tools, zero external API dependencies.18172 npm34MIT
- AlicenseAqualityCmaintenanceEvery FIFA World Cup since 1930 wrapped as 15 MCP tools — squads, brackets, stadiums, matches, awards, trivia. Powered by the Zafronix WC API.1512 npm3MIT
- AlicenseNot gradedqualityDmaintenanceExposes sqlite3 database functionality as MCP tools, enabling SQL query execution, schema management, and CRUD operations.82 PyPI1MIT
- AlicenseNot gradedqualityDmaintenanceProvides comprehensive SQLite database interaction through MCP, enabling CRUD operations, custom SQL queries, and database exploration.711 npm130MIT