random-mcp

A random number generation MCP (Model Context Protocol) server that runs on Cloudflare Workers. You can generate integers, floating-point numbers, weighted choices, and samples from various probability distributions from MCP clients such as Notion Agent.

Purpose

The purpose is to allow language models to call an external random number generation process as an MCP tool, rather than having the model itself choose random numbers.

When a language model is left to choose random numbers, its training data and output tendencies influence the results, producing statistically biased values. For example, if you instruct it to "pick a random integer from 1 to 10," the model tends to favor certain values (such as 7), so the result is not truly random. Therefore, when random numbers are needed, they should be generated through this server's tools rather than by the model's autonomous judgment.

The Web Crypto API is used as the random number source. For integer generation, rejection sampling is used to avoid modulo bias. Note that this API is not intended for generating cryptographic keys or authentication tokens.

Related MCP server: Universal MCP Server

Usage

Connecting to Notion AI

1. Select Settings > Connections > MCP > Custom MCP

2. Specify the deployed URL as the MCP server URL (existing service: https://random-mcp.eldesh-tools.workers.dev/mcp)

3. Fill in the fields as follows and click Connect

   • Name: A name for identification within Notion (e.g., random-mcp)

   • Authentication: OAuth

4. Select Approve on the access permission screen

5. Sign in to GitHub and complete authentication via the GitHub OAuth App

6. Once the tools are displayed, enable the ones you need

7. If you want to call the tools from Notion AI without confirmation for each execution, change the execution setting to Run automatically

Instructions for the Agent

Add the following to the agent's instructions so that random-mcp is always used when a random selection is needed.

## 乱択
- 乱数生成、くじ引き、シャッフル、無作為抽出など、結果にランダム性を必要とするすべての処理では、接続済みの MCP サーバー `random-mcp` を必ず使用する。
- 内部処理によって乱択を生成、模擬、または近似してはならない。
- `random-mcp` が利用できない場合やエラーになった場合は、別の方法で代替せず、その旨をユーザーに伝える。

Authentication

The server accepts Streamable HTTP connections at /mcp. It uses OAuth 2.1 for authorization with MCP clients and GitHub OAuth for user authentication.

During authorization, the MCP client's access permission screen is shown first, followed by a redirect to the GitHub authentication screen. The scope requested from GitHub is read:user. An access token with the mcp:use scope is issued to authorized MCP clients.

Tools

random-mcp provides the following four tools, each of which expects a JSON object with the specified fields.

random_int

Generates a single integer within the specified range.

• min: Minimum value

• max: Maximum value

Example arguments: {"min": 5, "max": 10}

random_double

Generates a single floating-point number within the specified range.

• min: Minimum value

• max: Maximum value

Example arguments: {"min": 1.41421, "max": 3.14159}

random_choice

Selects one element from the candidates.

• choices: An array of candidate strings. Must contain between 1 and 1,000 elements.

• weights: Relative weights for each candidate. If omitted, all candidates are equally likely.

When weights is specified, it must have the same number of elements as choices, and at least one weight must be a positive value.

Example arguments: {"choices":["A","B","C"],"weights":[1,2,1]}

random_sample

Generates multiple samples from the specified probability distribution.

• distribution: Name of the probability distribution

• parameters: Fields giving the parameters for the distribution

• count: Number of samples. Must be between 1 and 100; the default is 1

Additional computational limits apply.

• Binomial: trials must be an integer between 0 and 100,000, and trials * count <= 100000

• Poisson: lambda must be between 0 and 100, and lambda * count <= 10000

Example arguments: {"distribution":"uniform","parameters":{"min":5,"max":15},"count":3}

Development Environment

• Node.js 22.19.0 or later

• npm

• GitHub account

• Cloudflare account (required for deployment)

Install the dependencies.

npm install

Local Development

Creating a GitHub OAuth App

Create an OAuth App in GitHub's Developer settings. Since the callback URL differs between local and production environments, create a separate OAuth App for each.

Set the following values for the local development OAuth App.

• Homepage URL: http://localhost:8787

• Authorization callback URL: http://localhost:8787/callback

For the production OAuth App, replace http://localhost:8787 with the origin of the deployed Worker. The callback URL for the existing service is https://random-mcp.eldesh-tools.workers.dev/callback.

After creating the app, obtain the Client ID and Client secret. The OAuth scope this application requests from GitHub is read:user.

Environment Variables

Create .dev.vars in the project root.

GITHUB_CLIENT_ID=<GitHub OAuth App の Client ID>
GITHUB_CLIENT_SECRET=<GitHub OAuth App の Client secret>
COOKIE_ENCRYPTION_KEY=<Cookie の暗号化に使用するランダムな値>

COOKIE_ENCRYPTION_KEY can be generated, for example, with the following command.

openssl rand -hex 32

The temporary OAuth state is stored in the Cloudflare KV namespace specified by the OAUTH_KV binding in wrangler.jsonc. If you deploy to a different Cloudflare account, create a KV namespace and replace the id in wrangler.jsonc with that namespace ID.

Starting the Server

Start the local server.

npm run dev

The MCP endpoint is normally available at the following URL.

http://localhost:8787/mcp

[!NOTE] Even if Wrangler displays a warning that it cannot access Request.cf, as long as it finally shows Ready on http://localhost:8787 and this project does not use Request.cf, you can continue with verification.

Verification with MCP Inspector

With the local server running, launch the MCP Inspector web UI.

npx --yes @modelcontextprotocol/inspector@latest

In the Inspector, select Streamable HTTP and set the connection URL to http://localhost:8787/mcp. When connecting, the OAuth authorization flow starts in the browser, so allow access and complete GitHub authentication. To check the production environment, change the connection URL to the deployed MCP URL.

After connecting, verify that the tools listed in Tools appear on the Tools screen.

Deploying to Cloudflare Workers

Log in to Cloudflare.

npx wrangler login

Register the production GitHub OAuth App credentials and the cookie encryption key as Cloudflare Secrets.

npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
npx wrangler secret put COOKIE_ENCRYPTION_KEY

Verify that the GitHub OAuth App's Authorization callback URL points to /callback on the deployed Worker, and that OAUTH_KV in wrangler.jsonc points to an available KV namespace.

Deploy.

npm run deploy

The public URL is typically in the following format.

https://random-mcp.<subdomain>.workers.dev/mcp

[!IMPORTANT] .dev.vars is not automatically reflected in Cloudflare. The production Worker references the values registered in Cloudflare Secrets.

License

Released under the MIT License.