Snowbll MCP + CLI

Search the Snowbll game catalog, read your gaming persona, and follow Forge campaigns — from any MCP-capable AI agent or your terminal.

Everything in this package talks to the live Snowbll API (https://www.snowbll.com). There is no mock data.

Status: the search and Forge tools hit live public endpoints; the MCP servers, API keys, and the keyed v1 endpoints are in developer preview — names, fields, auth, and quotas may change before launch.

Two binaries ship in one package:

| Binary | What it is | | --- | --- | | snowbll-mcp | Model Context Protocol server over stdio — launched by agents (Claude, Cursor, Hermes, …) | | snowbll | CLI for humans — search, persona, Forge, key management |

There is also a hosted remote MCP server (developer preview) at https://www.snowbll.com/api/mcp (Streamable HTTP) for clients that connect to URLs instead of launching processes — ChatGPT connectors, Claude custom connectors, Hermes remote MCP. It is an OAuth 2.1 protected resource: MCP clients start the sign-in flow automatically on connect (no manual key needed); persona access uses the persona.read scope.

Tools

The MCP surface is deliberately read-only: tools recommend, explain, and retrieve. Nothing here buys games, backs campaigns, or moves money.

| Tool | What it does | Needs API key? | | --- | --- | --- | | search_games | Natural-language catalog search with ranked candidates + reasons | No | | get_game | Full metadata for one game, incl. human-verification status | No | | get_persona | The key owner's gaming persona — a playstyle + taste summary from their library and playtime (consent-scoped) | Yes — data visible from the Observer rank up; free accounts get a locked marker | | list_forge_campaigns | Forge campaigns with live funding totals | No | | get_forge_campaign | One campaign: tiers, stretch goals, progress | No |

Honesty model: verification is verified only after third-party human testing; quality fields (graphicsFidelity, economyComplexity) are null until a human rated them. AI recommends, humans judge.

Quick start (agents)

Claude Code

Hosted (remote, OAuth — no install):

claude mcp add --transport http snowbll https://www.snowbll.com/api/mcp

Then run /mcp and complete the OAuth sign-in when prompted — no manual key needed. Persona access uses the persona.read scope.

Or run it locally over stdio (uses SNOWBLL_API_KEY if set — see below):

claude mcp add snowbll -- npx -y snowbll-mcp

Claude Desktop / Cursor / Windsurf / Hermes (stdio)

{
  "mcpServers": {
    "snowbll": {
      "command": "npx",
      "args": ["-y", "snowbll-mcp"],
      "env": { "SNOWBLL_API_KEY": "sb_YOUR_API_KEY" }
    }
  }
}

Omit the env block to run keyless (search, game lookups, and Forge tools still work — only get_persona needs a key).

ChatGPT (remote connector — no install)

1. Settings → Connectors (requires a plan with connectors/developer mode).
2. Add a custom connector with URL https://www.snowbll.com/api/mcp, then complete the OAuth sign-in when prompted — no manual key needed. Persona access uses the persona.read scope.
3. Ask: "Use Snowbll to find an economy sim like Lemonade Tycoon with a deep economy."

The remote server also implements OpenAI's search / fetch connector contract, so it works in ChatGPT deep research too.

Claude (claude.ai custom connector / remote)

Add a custom connector with URL https://www.snowbll.com/api/mcp and complete the OAuth sign-in when prompted — no manual key needed. The catalog and Forge tools (search_games, get_game, list_forge_campaigns, get_forge_campaign) are free once connected; get_persona is consent-scoped via persona.read.

Verify any setup

Ask the agent:

Use search_games to find: "economy sim like Lemonade Tycoon with a deep economy"

A working setup returns a short candidate list, each with reasons.

Quick start (humans)

npm install -g snowbll-mcp

snowbll search "cozy farming game with deep crafting"
snowbll forge                 # campaigns on The Forge
snowbll login                 # mint + store an API key (email+password account)
snowbll whoami
snowbll persona               # your gaming persona
snowbll setup                 # wizard + ready-to-paste agent configs

API keys (developer preview)

Keys (sb_…) belong to Snowbll accounts and are hashed at rest — the plaintext is shown once.

• snowbll login — sign in with an email+password Snowbll account; mints and stores a key in ~/.snowbll/config.json.
• Accounts created with Google/Discord have no password: ask the Snowbll team for a preview key, then snowbll setup to paste it.
• snowbll keys list|create|revoke manages keys; SNOWBLL_API_KEY env always wins over the stored key.

Keep keys out of browser code, public repos, and shared transcripts.

Configuration

| Env var | Default | Purpose | | --- | --- | --- | | SNOWBLL_API_KEY | – | Developer-preview API key | | SNOWBLL_API_BASE | https://www.snowbll.com | API origin (point at a local dev server while developing) |

REST instead?

Everything the tools do is plain HTTP — POST https://www.snowbll.com/api/search is live with no key. Full docs: https://www.snowbll.com/docs.

License

MIT