Scorezilla MCP

What isco-tec/scorezilla-mcp does

isco-tec/scorezilla-mcp exposes the Scorezilla API as MCP tools for game and leaderboard administration. It can inspect the games associated with a developer account, enumerate boards, read leaderboard results, create resources, manage keys, and adjust selected configuration settings.

The main setup shortcut is bootstrap_leaderboard. It creates a game and its first board in one operation, then returns a widget embed, an SDK code sample, and a plain-language recommendation. For an existing game, use the separate game and board creation tools instead. SDK output can be tailored for anonymous or OAuth identities, client-only or server-validated anti-cheat, and TypeScript, Python, Go, or C#.

How it works

The server runs as a local stdio MCP process through npx -y @scorezilla/mcp. It sends requests to the Scorezilla API, which defaults to https://api.scorezilla.dev. Authentication uses the SCOREZILLA_TOKEN bearer token issued from the Scorezilla dashboard.

Write operations use an idempotency key derived from their arguments. If a create request times out and the same request is retried within five minutes, the API can return the original result rather than creating a duplicate. After a partial failure or an active slug conflict, inspect the account with list_games and list_boards before completing the setup with a narrower operation.

The process requires Node.js 20 or newer and network access to the Scorezilla API. A --read-only mode omits all resource-creation and configuration-update tools, which is useful for shared or CI client configurations.

Setup and configuration

Create an MCP token in the Scorezilla dashboard, then pass it as SCOREZILLA_TOKEN. Claude Code can register the server with claude mcp add, while Cursor can load a server entry from its MCP configuration using npx and the token environment variable. Claude Desktop can install the .mcpb package from the latest GitHub release and enter the token during setup. Other MCP-compatible clients can launch the same npm command with the environment variable set.

The optional SCOREZILLA_BASE_URL variable changes the API origin. The equivalent --base-url flag takes precedence when both are supplied. SCOREZILLA_BETA_TOKEN is retained for compatibility but is no longer needed for access.

Treat the MCP token as a bearer credential. Keep it out of source control and shared configuration, and revoke it from the Scorezilla account if it is exposed. The server returns a public key and secret-key prefix through get_keys, but the full game secret remains available only from the dashboard.

Tools and capabilities

• list_games and list_boards locate existing Scorezilla resources.
• get_board_top_n reads the leading entries on a board for integration checks.
• get_sdk_snippet produces integration code with identity, anti-cheat, and language options.
• bootstrap_leaderboard creates an initial game and board and returns embed and SDK material.
• create_game and create_board create resources separately.
• mint_key creates a new public and secret key pair; the secret is shown once.
• update_board_config changes score bounds and retention, including clearing a bound with null.
• update_game_config controls the browser-submit origin allowlist. An empty list permits all origins.

Board creation supports settings such as sort direction, score type, retention, and score bounds. Plan limits apply to game and board creation; failed limit checks return a plan_limit error and an upgrade link. Requests can also be rate-limited, with the response indicating when to retry.

Limitations and notes

The server operates on the games visible to the token's issuing developer account. Creating games and boards consumes the account plan's quotas; the free plan allows two games with three boards per game. Nothing is billed automatically when a plan limit is reached.

The default API endpoint can be replaced for staging or self-hosted deployments with the command-line flag or environment variable. The server itself does not expose the full game secret through MCP, so integrations that need it must retrieve it from the Scorezilla dashboard. The MIT-licensed package is distributed through npm as @scorezilla/mcp.