Claudinho

io.github.arturogarridoPublished by GitHub account arturogarridov0.15.0Updated Nov 22, 2026

Live football scores, fixtures and standings for 16 supported competitions. Unofficial fan project.

VerifiedSTDIODesktop onlyLocation & LifestyleData & Analytics

Overview

AI-generated overview

Lets an assistant answer football questions with live scores, fixtures, standings and shareable match cards for 16 competitions.

What you can do
  • Look up fixtures for a date, matches in play now, and a single match with goals and cards
  • Read standings tables and the World Cup knockout bracket
  • Find a team's next fixture and look up World Cup nations' codes, flags and groups
  • Produce plain-text share cards for matches, tables, brackets, dates or live scores
  • Read World Cup prediction-market odds and list supported competitions with their aliases
When to use it
Useful when you follow a league or tournament and want an assistant to answer score, fixture and table questions in chat, or to hand you a paste-ready match card. It is a fan project for casual match-day lookups, not an official data source.
Requirements
Runs locally over stdio via npx, so it needs Node.js 22 or later. No API key, signup or account. Optional environment variables set the default competition, team, language, timezone, commentary flavor and whether market signals are shown. Network access is needed for live data.
Before you install
All tools are read-only and nothing is written to disk, but live scores, schedules and odds are fetched from ESPN and Polymarket, which see standard request metadata such as your IP address. Prediction-market figures are informational only and not betting advice. It is an unofficial fan project, so answers can be partial or empty when provider data is unreadable.

Installation

In SourceWeft

  1. Open Claudinho in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[The Claudinho logo: a yellow C around a football, above the word claudinho]

@claudinho/mcp ⚽

An MCP server that lets your coding agent answer football questions: live scores, fixtures and standings 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.

[Cursor CLI asked mid-task how Manchester City are doing against Paris Saint-Germain; it calls the Claudinho MCP server and answers with the live score from the 24th minute]

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

bash
claude mcp add claudinho -- npx -y @claudinho/mcp

Codex CLI

bash
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.

json
{ "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:

bash
npx @claudinho/cli follow champions-league --team Arsenal

"What matches are on today?" · "Show me the live scores" · "When's our next game?"

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.

ToolWhat it does
get_todaythe fixtures for a date (default: today) in the caller's timezone, with live scores
get_livethe matches in play right now
get_matchone match by id, with the goals and cards the provider sent for a match in play or finished
get_next_fixturea 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_standingsthe standings: every table, or one by its key (a group letter, or A1, A-B, LEAGUE)
get_bracketthe 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_market_signalWorld 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_teama World Cup nation's name or code to its FIFA code, flag and group (offline)
list_competitionsthe supported competitions, the alias each takes (its name or a short form works too) 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, its name or a short form such as ucl, or an ESPN slug such as uefa.champions), 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 and get_match 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. The value is an alias, the competition's name (Premier League), a short form (epl) or an ESPN slug. An unknown value is a tool error that suggests the nearest alias when there is one and 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, 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 and get_market_signal 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. When the schedule ahead was read whole, an empty get_today may carry nextDay (the next local day with a fixture, and its count when known), an empty get_live may carry nextKickoff (the next kickoff ahead, never a match in play; nothing while one may be in play), and either may carry horizon when none falls in the next 14 days. 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 and get_match carry marketComplete, 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 says 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 ⚽

Source: packages/mcp/README.md at commit 4096118

Tools

9

get_today

Today's matches

All fixtures for a date (default: today), with live score and minute overlaid on any match in play. Optional prediction-market enrichment carries marketComplete; false means the read was incomplete, not that no signal exists. Off the World Cup, betweenEditions means the competition's edition ended before that date. partial means the provider sent records that could not be used: on the World Cup a fixture may then show from the bundled schedule without its live state (the text counts them, and names no provider when none shown was served), and where no bundled schedule was merged, an empty day means no fixture could be read for it, not that none is scheduled. Off the World Cup an empty day read whole may carry nextDay (the next local day with a fixture that is on, with count when known) or horizon (none in the next 14 days), when the schedule ahead was read whole. Use this for a whole day's card; for only in-play matches use get_live, for one team's match use get_next_fixture, for a single match's detail use get_match. Kickoffs render in tz; lang localizes the title, dates, status and stage words, the empty and outage sentences, attribution, and commentary (en/es/pt/fr); flavor sets commentary tone.

Parameterstzdatelangflavorcompetition

get_live

Live matches

Only matches in play right now, each with current score and minute; an empty list means nothing is in play only when the read was whole (neither partial nor degraded says otherwise). Off the World Cup, betweenEditions means the competition's edition has ended and the next has not started. partial means the provider sent records that could not be used: an empty list then means no match in play could be read, not that none is. Off the World Cup an empty list read whole may carry nextKickoff (the next kickoff ahead, never a match in play) or horizon (none in the next 14 days), when the schedule ahead was read whole and holds no match that may be in play now. Use during matches for in-play state; for a full day's schedule including upcoming and finished, use get_today. tz/lang/flavor affect formatting only.

Parameterstzlangflavorcompetition

get_match

Match detail

One match by its id, with live score/minute overlaid when it's in play, and, for a match in play or finished, the provider's goals and cards it could read (minute, kind, side, the player when named; match.events in data), never a claim that the list is every goal. Off the World Cup the id is looked for from yesterday to 14 days ahead: window names the provider days searched when it was not there (not found in that span, not "no such match"), and degraded with a match means its state could not be refreshed. Optional prediction-market enrichment carries marketComplete; false means the read was incomplete, not that no signal exists. Get the id from get_today or get_live; to find a team's match without an id, use get_next_fixture. tz/lang/flavor affect formatting.

Parametersidrequiredtzlangflavorcompetition

get_standings

Standings

Live cumulative standings: omit group for every table, or pass one table's key: a group letter (A–L in the World Cup), A1 for a numbered group, A-B for group B of league A, LEAGUE for a league's single table. Each table that is not a lettered group carries a label (the provider's name) and its title shows the key in parentheses. Returns ranked rows (team, played, W/D/L, goal difference, points). incomplete:true means a table could not be read and the tables returned are not the whole competition; a table with partial is missing rows. Use get_today for fixtures/scores and get_next_fixture for one team. If unavailable, the World Cup returns its roster at zero; competitions without a compatible bundled roster return no tables. Both are flagged degraded.

Parameterstzlanggroupflavorcompetition

get_bracket

Knockout bracket

Knockout bracket from the Round of 32 through the final, with live scores overlaid. Group slots project from live standings once a group has started; winner slots need a confirmed FT result. Pass an optional stage (R32, R16, QF, SF, 3P, F) to filter one round. partial means the provider sent records that could not be used: the ties shown are the ones read, and may not be all of them. Falls back to structure-only when live data is unavailable. A league season with no knockout tie of its own (the Premier League, LaLiga) answers inapplicable: there is none to show; other club competitions answer unsupported (not offered yet).

Parameterstzlangstageflavorcompetition

get_next_fixture

Next fixture for a team

A team's next match. World Cup: a nation's code or name (MEX, Mexico); a confirmed knockout tie is read from the live overlay, group fixtures from the bundled schedule. A club competition: a club's name or code (Arsenal, ARS), resolved against the competition's roster; its earliest match not yet finished in the 14 days ahead (in play included), with team (the club resolved), candidates when several teams match (no fixture is picked), horizon when none falls in that span, unknownTeam when neither the competition's table (read whole) nor its fixtures over those 14 days hold such a team, rosterIncomplete when the roster could not be read whole and the name (a code or a partial name) could not be resolved without it: ask again with the club's full name. partial means the provider sent records that could not be used: the answer is what was read, and no fixture then does not mean the team is out. With no team: the server's CLAUDINHO_TEAM, else the team the user pinned (claudinho follow <alias> --team <name>) when the request is for that team's competition; a tool error when there is neither.

Parameterstzlangteamflavorcompetition

get_market_signal

Prediction-market signal

Read-only prediction-market signals for a match (by id), a team's current-or-next fixture, or a date (default: today). Returns market-implied percentages with attribution; complete:false means the provider read was incomplete, not that no signal exists; partial says the same of the fixture read behind the answer (the provider sent fixture records that could not be used). Shown only before and during a match: finished matches have no market read. Informational only: relay the numbers factually; do not add betting, trading, or 'value' advice, and do not invent links.

ParameterstzdatelangteamflavormatchIdcompetition

get_team

Resolve a team

The World Cup roster: resolve a nation name or 3-letter code to its FIFA code, flag, and group. Fuzzy and forgiving: accepts "Mexico", "mex", "USA", "DR Congo", "Türkiye"/"Turkey", "Holland", etc. Useful for the 3-letter code get_market_signal needs. It knows no clubs: get_next_fixture resolves a club's name itself. Returns the single confident match (team), plus candidates (matches) when the query is ambiguous (e.g. "south" → South Africa, South Korea). Offline: reads the bundled roster, never the network.

Parametersqueryrequired

list_competitions

Supported competitions

The competitions Claudinho answers for, one per row: the alias every other tool's competition argument takes (it also takes the name or a short form), the name, the teams (nation or club), the kind (league or cup), and what each surface is (scores, next, standings, bracket, markets: offered, not-offered-yet, or not-applicable), plus current: the competition this request is for. Offline: reads the supported table, never the network. Whether an edition is in season is not listed here; the reads say so (betweenEditions).

Parameterslangcompetition

Version history

10
  1. v0.15.0LatestNov 22, 2026
  2. v0.14.0Nov 12, 2026
  3. v0.13.1Oct 29, 2026
  4. v0.13.0Oct 23, 2026
  5. v0.12.0Oct 18, 2026
  6. v0.11.2Oct 10, 2026
  7. v0.11.1Oct 10, 2026
  8. v0.11.0Oct 6, 2026
  9. v0.10.1Sep 16, 2026
  10. v0.10.0Sep 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts