NameWheel

What the NameWheel MCP server does

NameWheel MCP server connects an MCP-compatible client to NameWheel’s random selection and TrueSpin verification features. It can choose one or more winners from a supplied list, divide names into random teams, and create a public NameWheel link with the entries preloaded. These operations are useful for classroom participation, project assignments, games, raffles, and informal group decisions.

For decisions that need an auditable result, the server can create a certified draw. NameWheel publishes the title, entries, winner, and verification data on a permanent proof page. It can also freeze an entry list before the draw, list the connected account’s recent draws, and verify an existing draw without requiring an account.

How it works

The server supports two deployment styles. A local Node.js process communicates with clients over stdio; Docker can run the same process. The hosted endpoint uses Streamable HTTP at https://mcp.namewheel.org/mcp, so supported clients can connect without a local installation.

Local winner selection uses Node’s cryptographic random number generator. Team assignment and wheel-link generation happen locally as well. Verification fetches the public draw record and NameWheel public key, then checks the SHA-256 commitment, HMAC-SHA256 result, and Ed25519 signature locally.

Certified operations call the NameWheel API. The service commits to a secret before revealing it, combines connection randomness with the entry-list fingerprint, and publishes the resulting record after the draw. The proof page also exposes other certified draws run by the same account against the same list, making repeated attempts visible.

The server includes an in-chat wheel view for clients that support MCP Apps. Clients without that interface still receive the result as text.

Setup and configuration

For local use, clone the repository, install dependencies, build the project, and start dist/stdio.js with Node.js 20 or later. Docker users can build the supplied image and run it interactively. No environment variable is needed for local spins, team assignments, wheel links, verification, or basic plan checks.

Set NAMEWHEEL_API_KEY to a free API key when using certified_draw, freeze_list, or my_draws. The key can be created through NameWheel’s MCP page. Certified draw entries and frozen lists are public, so do not submit names that should remain private.

The hosted service can be added through the MCP connection settings of clients such as Claude, Cursor, ChatGPT, VS Code, Windsurf, Gemini CLI, Claude Code, or Codex CLI. Hosted connections without an account have rate limits of 30 calls per minute and 500 calls per day per connection. Account-required tools use the client’s connection flow or an API key supplied as a bearer token or API-key header.

Tools and capabilities

• spin_wheel: Selects one or more random winners and can display the wheel animation.
• make_teams: Creates random teams or groups using a team count or group-size instruction.
• open_wheel_link: Builds a NameWheel URL with the supplied entries loaded.
• certified_draw: Runs a public TrueSpin draw using an authenticated account.
• freeze_list: Publishes and locks an entry list before a later certified draw.
• verify_draw: Checks a draw code or link, including its commitment and signature.
• my_draws: Lists the account’s recent certified draws and frozen lists.
• check_plan: Reports available capabilities and the remaining daily certified-draw allowance.

The server also provides five prompts and two resources covering TrueSpin and usage limits.

Limitations and notes

Unauthenticated spins, team assignments, and wheel links do not store submitted names. Certified draws and frozen lists are stored by NameWheel and expose their entries publicly. Verification needs network access to retrieve the public record, while certified operations need the NameWheel API. A connected key is limited to certified draws, frozen lists, plan information, and that account’s draw history; it cannot modify account, payment, or other account data.

The local HTTP deployment has additional settings such as PUBLIC_URL, MCP_JWT_SECRET, NAMEWHEEL_API_URL, PORT, HOST, and STATE_DIR. These apply when self-hosting the HTTP server rather than using the default local stdio process. The project is released under the MIT license.