Click on "Install 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.
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 SQLiteFor 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
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.
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.
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.pyLaunch 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.
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.pyThe 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.
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.pyStart 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.
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.
Find every World Cup meeting between two countries and aggregate the results.
| Name | Required | Description | Default |
|---|---|---|---|
| gender | No | men | |
| team_a | Yes | First country to compare. | |
| team_b | Yes | Second country to compare. | |
| to_year | No | ||
| from_year | No |
| Name | Required | Description |
|---|---|---|
| gender | Yes | |
| team_a | Yes | |
| team_b | Yes | |
| matches | Yes | |
| summary | Yes | |
| to_year | Yes | |
| from_year | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose all behavioral traits. It mentions 'aggregate the results' but does not explain the aggregation method (e.g., win/loss/draw counts) or other behaviors like data freshness, read-only status, or rate limits. The statement 'every World Cup meeting' clarifies scope but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the core action and resource. There is no redundant information; every word contributes to the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to detail return values. However, it lacks context on the aggregation nature (e.g., summary statistics) and does not mention the optional parameters or their defaults. It is minimally complete for a simple tool but could be more informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 40% (only team_a and team_b have descriptions). The tool description adds no parameter-specific details beyond the schema, such as clarifying from_year, to_year, or gender usage. It does not compensate for the missing schema descriptions for other parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Find' and resource 'every World Cup meeting between two countries', with 'aggregate the results' specifying the outcome. It distinguishes from sibling tools like get_team_history (single team) and list_tournaments (list tournaments).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a user wants head-to-head history, but provides no explicit guidance on when to use it vs. alternatives (e.g., get_team_history for a single team's matches). No when-not-to-use or prerequisite information is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a player's appearances, starts, goals, and knockout record by tournament.
| Name | Required | Description | Default |
|---|---|---|---|
| gender | No | men | |
| player | Yes | Player name, such as Lionel Messi or Kylian Mbappé. | |
| to_year | No | ||
| from_year | No |
| Name | Required | Description |
|---|---|---|
| teams | Yes | |
| gender | Yes | |
| player | Yes | |
| totals | Yes | |
| to_year | Yes | |
| from_year | Yes | |
| birth_date | Yes | |
| tournaments | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, but it only states what data is retrieved without mentioning side effects, authentication needs, or rate limits. It does not disclose that this is a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the tool's function with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema is present, so return values need not be described, but the description lacks context for parameter usage and does not mention the optional parameters or default values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, and the description does not explain parameters beyond the minimal information in the schema. The 'by tournament' hint does not clarify the gender or year range parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool retrieves a player's appearances, starts, goals, and knockout record by tournament, using specific verbs and resource. It distinguishes from sibling tools like list_tournaments, get_team_history, and get_head_to_head.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention any prerequisites or limitations for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a country's tournament-by-tournament record and aggregate World Cup totals.
| Name | Required | Description | Default |
|---|---|---|---|
| team | Yes | Country name, such as Argentina, France, England, or Japan. | |
| gender | No | men | |
| to_year | No | ||
| from_year | No |
| Name | Required | Description |
|---|---|---|
| team | Yes | |
| gender | Yes | |
| totals | Yes | |
| to_year | Yes | |
| from_year | Yes | |
| best_finish | Yes | |
| tournaments | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description carries full burden but only states purpose. Fails to disclose any behavioral traits like permissions, idempotency, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise and front-loaded. However, could include a brief note on parameters without sacrificing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description lacks context for filtering (year range, gender) and does not mention the output structure. Minimal completeness for a moderately complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (25%), and description adds no parameter-specific context. The only parameter description in schema is for 'team'; description omits details about gender, date range, or defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Get' and specific resource: a country's tournament-by-tournament record and aggregate World Cup totals. Unambiguously distinguishes from sibling tools like list_tournaments and get_head_to_head.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. Does not mention prerequisites, filters, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the World Cup tournaments available in the local database.
| Name | Required | Description | Default |
|---|---|---|---|
| gender | No | men |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| gender | Yes | |
| tournaments | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states a simple list operation. It does not disclose pagination, ordering, or whether the output includes full tournament details. The existence of an output schema helps but the description adds no behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it sacrifices necessary detail. It is appropriately front-loaded but lacks parameter and behavioral information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema exists), the description should at least mention the gender filter and the type of data returned. It fails to do so, making it incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not mention the 'gender' parameter at all. The agent receives no explanation of what the parameter does, despite it having an enum and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), resource ('World Cup tournaments'), and scope ('in the local database'). It distinguishes from sibling tools which focus on teams, head-to-head, and players.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention any prerequisites, filtering options beyond what's implied, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.2.0get_head_to_headget_player_recordget_team_historylist_tournamentsEach 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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
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
OpenLigaDB MCP — community-run, keyless football / soccer match data.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/lukejbyrne/world-cup-stats-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server