Random MCP

What random-mcp MCP server does

The random-mcp MCP server gives MCP clients three tools for generating values outside the language model’s own output process. random_int returns integer arrays, random_double returns floating-point arrays, and random_choice selects values from a supplied list. The tools are intended for random selection, sampling, lotteries, shuffling-related workflows, and other tasks where the agent should not choose the result internally.

Randomness comes from the Web Crypto API. Integer generation uses rejection sampling to avoid modulo bias. The project states that these APIs are not intended for creating cryptographic keys or authentication tokens.

How it works

The official service accepts Streamable HTTP connections at https://random-mcp.eldesh-tools.workers.dev/mcp. MCP authorization uses OAuth 2.1, while user authentication is handled through GitHub OAuth. The GitHub permission requested is read:user; an authorized MCP client receives an access token with the mcp:use scope.

random_int supports uniform, Bernoulli, binomial, and Poisson distributions. random_double supports uniform, normal, lognormal, and exponential distributions. random_choice accepts candidate strings, optional relative weights, a selection count, and a replacement setting. Results are returned in a values array.

Integer and floating-point tools accept between 1 and 1,000 requested values. Binomial requests limit trials * count to 100,000, while Poisson requests limit lambda * count to 10,000. Choice lists may contain 1 to 1,000 strings. Without-replacement selection cannot request more items than available candidates, or more than the number of candidates with positive weights when weights are supplied.

Setup and configuration

For the hosted instance, configure an MCP client with the official /mcp URL and complete the OAuth approval and GitHub sign-in flow. The README specifically documents connection steps for Notion AI and testing with MCP Inspector.

To run a private deployment, use Cloudflare Workers, a Cloudflare account, a KV namespace for temporary OAuth state, and a GitHub OAuth App. The OAuth callback must point to the deployed Worker’s /callback path. The random-mcp MCP server expects GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, and COOKIE_ENCRYPTION_KEY; the first two identify the OAuth App and the last protects cookies. GLAMA_MAINTAINER_EMAIL is optional for the local Glama metadata check.

Local development requires Node.js 22.19.0 or later and npm. Install dependencies with npm install, place local values in .dev.vars, and start the Worker with npm run dev. The local MCP endpoint is normally http://localhost:8787/mcp. A custom deployment can be published with npm run deploy after configuring the Worker name, OAuth App, KV binding, and Cloudflare secrets.

Tools and capabilities

• Generate uniform, Bernoulli, binomial, or Poisson integer samples.
• Generate uniform, normal, lognormal, or exponential floating-point samples.
• Select candidates with equal or relative weighted probability.
• Select with or without replacement.
• Request batches of values through each sampling tool.

Limitations and notes

The random-mcp MCP server does not replace a cryptographic randomness service. Tool inputs must meet the documented bounds, including distribution-specific limits and the restrictions on weighted sampling without replacement.

Use the Inspector CLI or another client method when testing those tools. If an agent must always use this service for random operations, its instructions should explicitly prohibit internal randomization and require an error report when the server is unavailable.