@claudinho/mcp ⚽
An MCP server that lets your coding agent answer football questions: live scores, fixtures, standings and paste-ready match cards for the competition you follow: the World Cup, the Premier League, LALIGA, the Champions League and 12 more. It works in Claude Code, Cursor, Codex, Claude Desktop, Windsurf, Zed, VS Code and any MCP client that runs a local (stdio) server. No API key, no signup, no account.
Install
The server runs with npx, so it needs Node.js 22 or later. That is the oldest line it runs on, not a security
level: run a patched release of the Node 22 or 24 line.
Claude Code
claude mcp add claudinho -- npx -y @claudinho/mcp
Codex CLI
codex mcp add claudinho -- npx -y @claudinho/mcp
Cursor, Claude Desktop, Windsurf, Zed, VS Code: add this to the client's MCP config (for
Cursor, ~/.cursor/mcp.json or a project's .cursor/mcp.json; for Claude Desktop, Settings →
Developer → Edit Config, then restart). Some clients (VS Code, Zed) put the same command and
args under a key of their own: see your client's MCP docs.
{ "mcpServers": { "claudinho": { "command": "npx", "args": ["-y", "@claudinho/mcp"] } } }
Using Cursor CLI too? claudinho init cursor (from @claudinho/cli) puts the live score in its
statusline and prints this config for you to paste.
Ask your first question
The server answers for one competition at a time. Either name it in your question:
"What Champions League matches are on today?" · "Show me the Premier League table" · "When does Arsenal play next in the Champions League?"
or choose it once with the CLI, and then just ask:
npx @claudinho/cli follow champions-league --team Arsenal
"What matches are on today?" · "Show me the live scores" · "When's our next game?" · "Make me a shareable card for today"
Without a competition, the tools that answer for one say how to choose it.
Tools
Every tool is read-only, and two of them never touch the network.
| Tool | What it does |
|---|---|
get_today | the fixtures for a date (default: today) in the caller's timezone, with live scores |
get_live | the matches in play right now |
get_match | one match by id, with the goals and cards the provider sent for a match in play or finished |
get_next_fixture | a team's next match, by name or code (Arsenal, ARS, Mexico, MEX); with no team, the server's CLAUDINHO_TEAM, else the team the user pinned (claudinho follow <alias> --team <name>) when the request is for its competition |
get_standings | the standings: every table, or one by its key (a group letter, or A1, A-B, LEAGUE) |
get_bracket | the knockout bracket, World Cup only, from the Round of 32 to the final; an optional stage (R32, R16, QF, SF, 3P, F) keeps one round |
get_share_snippet | a plain-text card for a match, a team's next match, a table, the bracket (bracket: true, with an optional knockoutStage), a date or live; hand it to the user as it is |
get_market_signal | World Cup prediction-market odds for a match (matchId), a team's current or next match (team, a 3-letter code such as MEX), or a date; informational only |
get_team | a World Cup nation's name or code to its FIFA code, flag and group (offline) |
list_competitions | the supported competitions, the alias each takes and what each offers, and the one in effect (offline) |
Every tool but get_team takes an optional competition (an alias such as champions-league), and
most take tz, lang (en, es, pt, fr) and flavor (off, subtle, full).
A call with no lang, or an empty one, takes the server's CLAUDINHO_LANG when it is exactly en,
es, pt or fr, else answers in English. get_team takes no lang, and the resources answer in
English.
Resources: standings://{group}, and fixtures://{date} (the bundled World Cup schedule).
Prompts: my_team (your team's next match and its standing, in the competition you follow) and
tournament_today.
Prediction-market odds (World Cup)
For World Cup matches, get_today, get_match and a get_share_snippet card for a match, a
team's next match or a date add a short "who's favored" line when a reliable Polymarket market
exists, and get_market_signal reads one on its own. Informational only, not betting advice:
market-implied percentages with Polymarket's attribution, never links or trade calls. Finished
matches never show one. CLAUDINHO_MARKETS=off in the server's env turns the short line off;
get_market_signal still answers.
Commentary
A match line in a tool's text ends with a short line of commentary in the reader's language
(— ¡GOOOOL!), or a team's own rally cry when it has one (Mexico's ¿Y si sí?, Pumas' ¡Goya!,
Arsenal's COYG!). A postponed or cancelled match gets neither. The commentary never appears in
the structured data. Turn it down with CLAUDINHO_FLAVOR=subtle or off in the server's env, or
per call with flavor.
Details for agent builders
Choosing the competition. A request's competition is its competition argument, else the
server's CLAUDINHO_COMPETITION, else the choice claudinho follow <alias> saved. An unknown value
is a tool error that lists the aliases. With none of the three, every competition-answering tool
answers noCompetition: true and competition: null beside its empty shape, with a sentence saying
what to do; list_competitions answers current: null.
What every answer carries. Human-readable text and structured content, validated against each
tool's declared outputSchema. The text starts with the competition it is for (a share card says it
in its title), and the structured content carries it as competition. Two tools differ:
get_team reads the World Cup's nations whatever the competition and carries no competition, and
list_competitions names the one in effect last in its text and as current in its data.
Answers that are not whole. When the provider sent records that could not be read,
get_today, get_live, get_match, get_next_fixture, get_bracket, get_market_signal and
get_share_snippet say so before what they show and carry partial (with omitted, the count of
records left out, when it is known). An empty answer then means nothing was read, not that nothing
exists. In particular, a missing next match does not mean a team is out.
Club competitions. get_next_fixture and get_match search from yesterday to 14 days ahead:
an empty answer carrying horizon or window is about that span. Several teams matching one name
come back as candidates. Between two seasons, get_today, get_live, get_next_fixture and
get_match carry betweenEditions. get_bracket answers inapplicable for a league season with no
knockout tie (the Premier League, LALIGA), and unsupported for every other competition but the
World Cup. A club has no flag. A match's stage is REGULAR for a league's season, LEAGUE for
a cup's league phase, PO for play-offs, or OTHER with the provider's own words in stageLabel.
Markets. get_today, get_match and a get_share_snippet card for a match, a team's next
match, a date or live matches carry marketComplete (a table or bracket card does not), and
get_market_signal carries complete. false means the
optional market read did not finish, which is not the same as "no signal"; the text, and a share
card, say so too. CLAUDINHO_MARKETS_SOURCE=fake gives a clearly labelled, network-free preview.
The process. Stdout carries only the MCP protocol; diagnostics go to stderr.
CLAUDINHO_DEBUG=1 in the server's env prints the data provider's failures there.
How it works
The World Cup's 104 fixtures ship with the package. Every other competition's schedule, and every live score, comes from ESPN's public scoreboard (an answer from it names ESPN). World Cup market odds come from Polymarket's public data. The server keeps its cache in memory only.
Privacy
No accounts, no telemetry, no analytics, no tracking, and no Claudinho server. The server asks ESPN (and Polymarket, for World Cup odds) for public data with nothing about you attached; those services still see standard request metadata, such as your IP address, like any web request. It writes nothing to disk. Full policy: PRIVACY.md.
License
MIT © 2026 Arturo Garrido · source and issues
Independent fan project. Not affiliated with FIFA, any confederation, league or club, or Anthropic.
Built while watching the games. #VibingLaVidaLoca ⚽