@statospro/mcp

A Model Context Protocol server that connects AI assistants — Claude Desktop, Claude Code, claude.ai — to your Statos account.

Statos is a football analytics platform: it models match outcomes across ten markets and prices them against live bookmaker odds. This package wraps the api.statos.pro REST surface in an API-key-authenticated, AI-friendly tool layer, so an assistant can answer "what does the model like today?" without you writing a single HTTP call.

npx -y @statospro/mcp@latest --api-key statos_sk_live_xxxxxxxx

Tools

v0.3.0 — full read surface plus admin controls.

The four read tools are available to any account. The three market-suppression tools are an operational kill switch — they let an admin stop the engine emitting a (league × market) combination for a time window without shipping a deploy. They require an admin-role key carrying the admin:market_suppressions scope, which is not in the default scope set.

Upgrading from v0.1? API keys minted before the v0.2 release carry only read:suggestions. Regenerate your key to pick up read:leagues and read:account, or list_leagues and get_account will 403.

Related MCP server: kicktipp-agent

Quick start

1. Get a Statos API key

Log in at https://statos.pro/account, open the API keys card, and create a key. Copy the statos_sk_live_… token — Statos shows it once.

2a. Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "statos": {
      "command": "npx",
      "args": ["-y", "@statospro/mcp@latest"],
      "env": {
        "STATOS_API_KEY": "statos_sk_live_xxxxxxxx"
      }
    }
  }
}

Restart Claude Desktop. The tools appear in the tools picker.

2b. Claude Code

claude mcp add statos -- npx -y @statospro/mcp@latest --api-key statos_sk_live_xxxxxxxx

2c. Test against sandbox first (optional)

claude mcp add statos-sandbox -- npx -y @statospro/mcp@latest \
  --api-key statos_sk_test_xxxxxxxx \
  --api-base https://api.sandbox.statos.pro

Tool reference

list_picks

List the model's current suggestions, optionally filtered.

Returns an array of BetSuggestion objects (match info, market, selection, suggested_prob, best_odds, edge, confidence) plus filter metadata and any truncation notes.

get_match_picks

Every suggestion for a single match — for "what does the model think about match X?" queries.

list_leagues

Discover league IDs to filter list_picks against. Returns the leagues the key holder's plan can see.

get_account

Read-only account info: email, role, subscription status, and effective role (trial-elevated while a trial is active). Useful for "what plan am I on" and for working out which leagues are visible.

No input. Returns { account, effective_role, notes? }.

suppress_market / list_suppressions / unsuppress_market

Admin-only. suppress_market takes league_id (0 = all leagues), market, and duration_hours; the others take nothing and an id respectively. Requires backend ≥ v1.16.

Configuration

Troubleshooting

• 401: invalid or revoked API key — the key was deleted in the Statos UI, or the token was truncated on copy. Regenerate at /account → API keys.

• 401: missing or malformed Authorization header — the env var or --api-key flag isn't reaching the server process. Restart your MCP client after editing config files.

• 403 on list_leagues / get_account — your key predates v0.2 and lacks the scopes. Regenerate it.

• No picks for any filter — either a quiet day for the model, or your plan's league entitlements exclude what you asked for. Try list_picks with no filters first.

Versioning

The package version is independent of the Statos API version. The server sends User-Agent: @statospro/mcp/<version> so backend logs can correlate. Breaking changes to the /suggestions schema trigger a major bump; additive changes (new fields) are minor. See CHANGELOG.md.

Roadmap

• v0.2 — list_leagues + get_account ✓ shipped

• v0.3 — market-suppression tools ✓ shipped

• v0.4 — backend match_id filter on /suggestions, so get_match_picks stops fetching and filtering client-side

• v0.x — friendlier zod-error rendering (currently the raw issue array — readable, but verbose)

• v1.0 — remote SSE/HTTP transport for one-click connect, no npx step

Requirements

Node.js ≥ 20. A Statos account with an API key.

License

MIT — see LICENSE.