io.github.isco-tecPublished by GitHub account isco-tecv0.4.5Updated Oct 29, 2026
Official Scorezilla MCP: add a global leaderboard to your game by asking Claude Code or Cursor.
Official Scorezilla MCP server that lets an AI coding assistant create games and leaderboards and generate SDK integration code from the editor.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
[npm version] [license: MIT] [scorezilla-mcp MCP server]
Add a global leaderboard to your game by asking Claude Code or Cursor. The SDK it wires in is ~5 KB gzipped, with zero runtime dependencies.
Official Model Context Protocol (MCP) server for Scorezilla. Connect it to your AI coding assistant (Claude Code, Cursor, Continue.dev, …) and ship a working leaderboard without leaving your editor.
Eleven tools total — five read-only, and six that write: four that create resources (bootstrap_leaderboard, create_game, create_board, mint_key) plus two that update config (update_board_config — score bounds + retention, e.g. an anti-cheat maxScore; update_game_config — the browser-submit origin allowlist).
Access — open to every Scorezilla account. Sign up free at dashboard.scorezilla.dev, create a token, and go. Creating games and boards counts toward your plan's limits (Free: 2 games × 3 boards each); when you hit one, the tool error includes a direct upgrade link. See pricing.
Sign in at dashboard.scorezilla.dev, open MCP tokens, click Create token. Copy the mcp_live_* value once — it's not shown again.
Claude Code — one command (--scope user makes it available in every project):
Cursor — add this to ~/.cursor/mcp.json (or Settings → MCP → Add new MCP server):
🔒 Keep your MCP config private. Both clients store the token in plaintext (
~/.claude.jsonfor Claude Code,~/.cursor/mcp.jsonfor Cursor). Don't commit it to git, sync it to a public dotfiles repo, or back it up to a shared location. On macOS/Linux,chmod 600the file so only your user can read it. If a token leaks, revoke it at dashboard.scorezilla.dev/account/tokens.
Claude Desktop — one click: download scorezilla-mcp.mcpb from the latest release, double-click it, and paste your mcp_live_… token when Claude Desktop asks. The token is kept in your system's secure credential store.
Anything else MCP-compatible — point your client at npx -y @scorezilla/mcp with SCOREZILLA_TOKEN set in the environment.
In Claude Code or Cursor: "Add a Scorezilla leaderboard to this game."
The create tools (bootstrap_leaderboard, create_game, create_board, mint_key) send an Idempotency-Key derived from their arguments. If a call times out and your assistant retries it with the same arguments within 5 minutes, the API returns the original result instead of creating a duplicate: the same game and board for bootstrap_leaderboard, the same key pair for mint_key.
After that window, or if bootstrap_leaderboard returns partial_failure or slug_taken_active, don't bootstrap again. Call list_games (and list_boards) to see what exists, then finish with create_board or mint_key.
Creating games and boards counts toward your Scorezilla plan's limits (Free: 2 games × 3 boards each; see pricing). When a write would go past a limit, the tool returns a plan_limit error with the limit and a direct upgrade link, which your assistant can pass on. Nothing is ever billed automatically. Requests are also rate-limited per token and per account; a rate_limited error says when to retry.
--read-only — refuse to register the write tools (bootstrap_leaderboard, create_game, create_board, mint_key, update_board_config, update_game_config). Use this on shared/CI configs to guarantee the AI can't create or change resources.--base-url=<url> — override the API origin. Defaults to https://api.scorezilla.dev. Useful for self-hosted or staging environments.SCOREZILLA_TOKEN — required. Bearer token issued at dashboard.scorezilla.dev/account/tokens.SCOREZILLA_BASE_URL — same as --base-url, but via env. CLI flag wins if both are set.SCOREZILLA_BETA_TOKEN — no longer needed; the MCP is open to every account. Kept for compatibility (sent as X-MCP-Beta when set).env blocks, password managers, or secret stores.https://api.scorezilla.devReleases are CI-driven and require an approval click in the npm-publish GitHub Environment. The full flow:
pnpm changeset — describes what changed and the bump type. Commit the file under .changeset/..github/workflows/release.yml runs and opens a "chore(release): version @scorezilla/mcp" PR that bumps package.json, syncs server.json (the MCP Registry manifest) via scripts/sync-server-json-version.mjs, and updates CHANGELOG.md.--provenance (verifiable build attestation via GH OIDC + sigstore), plus a @scorezilla/mcp@<version> git tag and GitHub release (notes from CHANGELOG.md)mcp-publisher login github-oidc → mcp-publisher publish, only after the smoke test passes; it waits for npm to serve the version and retries while the Registry can't see it yetnode dist/index.js --version), and release:check (asserts package.json and server.json versions agree).Manual publishes from a developer terminal still work (bash scripts/publish.sh) but aren't the path CI takes — they skip provenance and approval gates. Use only for one-off recovery.
MIT.
Source: README.md at commit c7e5efc
List all games owned by the authenticated developer. Returns each game with id, slug, name, and createdAt. Use this first to orient before creating new resources or inspecting an existing game. If the result is an empty list and the developer wants to add a leaderboard, call bootstrap_leaderboard next.
Takes no parameters.
List all leaderboards (boards) under a given game. Each board has its own id, slug, ranking (sortDir: desc = high-score-wins, asc = lowest-time-wins), score kind (integer / duration_ms / float), retention policy, and optional min/max score bounds. Call this to find a board's id before generating a snippet (get_sdk_snippet) or reading standings (get_board_top_n), or to show the developer what boards already exist under a game returned by list_games.
gameIdrequiredGet a game's API keys. Returns, per key: kind ('public' | 'secret'), prefix, createdAt, and rotation/revocation timestamps. The PUBLIC key includes its full plaintext (it's safe to embed in client code). The SECRET key's plaintext is ALWAYS null over MCP — only its prefix is shown, for identification. Use this to retrieve the public key for a client_only integration, or to check which keys exist / have been revoked. If the developer needs the full SECRET key (for a client_with_server / server_only anti-cheat setup), direct them to https://dashboard.scorezilla.dev — the Keys section under their game — since it never leaves the dashboard.
gameIdrequiredGet the top-ranked entries on a leaderboard. Call this after the developer submits a test score to confirm the integration is wired correctly — they will see their own test entry appear. Also useful for displaying current standings.
nboardIdrequiredCall this whenever the developer asks how to submit a score, initialize the SDK, or integrate a leaderboard into their code — INCLUDING when they want a setup other than the default: anti-cheat (server-validated scores), OAuth player identity, or a non-TypeScript server. Returns a ready-to-paste integration snippet (the `snippet` field) tailored to the axis arguments. Omit the axis args for the simplest anonymous + client-only TypeScript setup; set hostingPattern='client_with_server' (+ a serverLanguage and/or auth provider) for the secure anti-cheat path. Use it right after bootstrap_leaderboard, or any time the developer needs the integration code again or wants to switch approach. (For the drop-in widget HTML embed, bootstrap_leaderboard returns it as snippets.widget.)
gameIdrequiredboardIdrequiredauthProviderhostingPatternserverLanguageplayerIdentityStrategyUse this when starting from scratch — creates a new game AND its first board in one call, then returns ready-to-paste integration code wired against the board. The fastest path from "I want a leaderboard" to "scores are flowing." Do NOT call this if the developer already has games — call list_games first and use bootstrap_leaderboard only when no game exists yet. The response includes `snippets.sdk` (framework/server code), `snippets.widget` (a themeable drop-in HTML embed; null for server_only), and a plain-English `recommendation` to relay to the developer — paste `snippets.sdk` (and/or `snippets.widget`) into their code. The optional axis args tailor the output: set hostingPattern='client_with_server' for anti-cheat (server-validated scores), playerIdentityStrategy='auth_provider' (+ authProvider) for OAuth identity, or serverLanguage for a non-TypeScript server. Omit them all for the simplest anonymous + client-only setup. Retry-safe: if a call times out or the connection drops, calling it again with the SAME arguments within 5 minutes returns the original game and board instead of creating a duplicate. After that window, or on a partial_failure or slug_taken_active error, do NOT bootstrap again — call list_games to see what was created, then finish with create_board / mint_key.
sortDirgameNamerequiredgameSlugrequiredboardNamerequiredboardSlugrequiredscoreKindauthProviderhostingPatternserverLanguageplayerIdentityStrategyCreate a new (empty) game in the developer's account. Use this when they ALREADY have a game (so bootstrap_leaderboard would conflict) or want an additional game — call list_games first to check. Returns the gameId; follow up with create_board to add leaderboards and mint_key for keys. For a first-ever game from scratch, prefer bootstrap_leaderboard (it does game + board + keys + code in one call).
namerequiredslugrequiredAdd a leaderboard board to an EXISTING game (by gameId — get it from list_games). This is how you add boards to a game that already exists; bootstrap_leaderboard only works for brand-new games. sortDir "desc" = high-scores-win, "asc" = lowest-time-wins. Returns the created board including its id.
namerequiredslugrequiredgameIdrequiredsortDirmaxScoreminScorescoreKindretentionNretentionPolicyMint a fresh public/secret key pair for an EXISTING game (by gameId). Returns publicKey (pk_ — safe for the browser/widget) and secretKey (sk_ — server-only, shown ONCE; tell the developer to store it now). Use when a game needs keys, or to add another pair. Key revocation/rotation is done in the dashboard. Note: the secret also appears in this MCP host's tool-call transcript, so treat the conversation as sensitive until cleared.
gameIdrequiredUpdate a board's scoring config AFTER creation (by gameId + boardId — from list_games / list_boards). PARTIAL: only the fields you pass change. Use it to cap scores for anti-cheat (maxScore), set a floor (minScore), or change retention. A bound can be cleared by passing null. Returns the full updated board.
gameIdrequiredboardIdrequiredmaxScoreminScoreretentionNretentionPolicySet a game's allowed-origins allowlist AFTER creation (by gameId — from list_games). Restricts browser score submissions to specific web origins: an exact origin like "https://yourgame.com" or a wildcard host like "*.yourgame.com" (up to 20). Pass an empty array to allow all origins (the default). Returns the normalized stored list. Gates browser requests only — server-to-server calls send no Origin header.
gameIdrequiredallowedOriginsrequired90% 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.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
claude mcp add scorezilla --scope user -e SCOREZILLA_TOKEN=mcp_live_… -- npx -y @scorezilla/mcp{ "mcpServers": { "scorezilla": { "command": "npx", "args": ["-y", "@scorezilla/mcp"], "env": { "SCOREZILLA_TOKEN": "mcp_live_…" } } }}scorezilla-mcp [--read-only] [--base-url=<url>] [--version] [--help]