Matching provider IDs without the traps: reep 0.1 and nutmeg 0.5.1

Every football data provider has its own IDs. Joining Transfermarkt to Wyscout to Opta means a crosswalk, and the Reep Register is a free one (CC0): one stable Reep ID per player, team, match and more, with each provider’s IDs attached.

Using it correctly is harder than it looks. Reep IDs merge when two turn out to be the same person, and when they do, some provider IDs stay attached to the old ID. Providers retire IDs without telling you. Some IDs are withdrawn.

What reep is

reep is a Python package for the register (documentation). It is a command-line tool, a Python SDK and a read-only MCP server for AI agents.

• Lookups that handle the traps. It resolves a provider ID, given in full (provider, namespace and ID), to its current Reep ID. Merged IDs resolve to the survivor, and a withdrawn ID comes back with a status, never an empty answer. Translations list live IDs first and mark IDs a provider has retired or removed.
• Stored IDs, checked. current tells you what to do with a Reep ID you saved earlier: keep it, store the survivor it was merged into, or review it because it was withdrawn.
• Your own tables. It adds Reep IDs to pandas, polars or pyarrow tables, and reep sync fills Reep IDs and other providers’ IDs into your own PostgreSQL, MySQL, SQL Server or SQLite tables. It runs as a dry run unless you add --apply, writes only to empty cells, and lists the rows that need a person to review.
• Works offline. reep catalog sync downloads the register (about 210 MB, free, no key) and checks every file. It can also read a register file you already have, or the hosted API with a key.
• Built for agents. JSON output with a versioned envelope, fixed exit codes, a skill file, and an MCP server with seven read-only tools: resolve, translate, current, entity, search, providers and status.

What you can do with it

1. Add other providers’ IDs to a table you already have. A squad list with Transfermarkt IDs gets Opta and Wyscout IDs alongside, in one pass, with the rows it can’t match listed for review.
2. Keep stored IDs current. Check the Reep IDs in your database against each new release, and update the merged ones to their survivor.
3. Let your agent do the lookups. With the MCP server, an agent translates IDs during an analysis instead of guessing them or writing a join by hand.
4. Look things up without a network. Once the register is downloaded, every lookup runs locally.

nutmeg 0.5.1

nutmeg 0.5.1 can use reep. When a task needs many ID lookups, or Reep IDs in your database, nutmeg offers the reep MCP server, and it never adds it without asking. Without it, nutmeg uses football-docs’ resolve_entity, as before.

The two routes give the same answers. football-docs 0.17.4 also follows merged IDs to the survivor, keeps the provider IDs still attached to the merged ID, marks retired and removed IDs, and reports withdrawn IDs as withdrawn. If you already have the register file for football-docs, reep can read the same file.

Why not just

• Match by name? The public register has no dates of birth, so name matching is unreliable. reep matches by provider ID only, and sends anything else to manual review.
• Write the join yourself? You can, but you have to handle merged IDs, retired IDs and withdrawn IDs every time.
• Use the hosted API alone? It needs a key, and is built for just-in-time, single lookups. reep can use it, but the local register is better for bulk work.

What it doesn’t do

• It doesn’t guess. No fuzzy or name matching: rows without an exact provider ID go to review.
• It doesn’t overwrite your data. reep sync fills empty cells only, and only after you ask it to apply.
• It doesn’t fix the register. If an ID is wrong, report it at reep.football/submit.
• It is a first release. Pin it to 0.1 (reep>=0.1,<0.2), as the set-up command below does.

Try it

pip install reep              # or: uv tool install reep
reep catalog sync             # the register, about 210 MB, free
reep resolve transfermarkt spieler 568177

For your agent (needs uv):

claude mcp add --scope user reep -- uvx --from 'reep[mcp]>=0.1,<0.2' reep mcp

Already using nutmeg? Run /plugin update nutmeg.

Which provider pairs do you join most? Tell me, and I’ll check how well the register covers them.