random-mcp

运行在 Cloudflare Workers 上的乱数生成用 MCP（Model Context Protocol）服务器。可以从 Notion Agent 等 MCP 客户端生成整数、浮点数、加权选择以及各种概率分布的样本。

目的

本项目的目的是不让语言模型自行选择乱数，而是通过 MCP 工具调用外部的乱数生成处理。

如果将乱数的选择交给语言模型，模型的训练数据或输出倾向会影响结果，从而生成统计上存在偏差的值。例如，即使指示“从1到10中随机选择一个整数”，模型也倾向于偏好特定值（如7），这并非真正意义上的乱数。因此，需要乱数的处理不应由模型自主判断，而应通过本服务器的工具来生成。

乱数源使用 Web Crypto API。在整数生成中，为了避免取余导致的偏差，采用 rejection sampling。不过，本 API 并非用于生成加密密钥或认证令牌。

Related MCP server: Universal MCP Server

使用方法

连接到 Notion AI

1. 选择 Settings > Connections > MCP > Custom MCP

2. 在 MCP server URL 中指定已部署的 URL（现有服务：https://random-mcp.eldesh-tools.workers.dev/mcp）

3. 按如下方式填写各项并点击 Connect

   • Name: 用于在 Notion 中识别的名称（例如：random-mcp）

   • Authentication: OAuth

4. 在访问许可画面中选择 Approve

5. 登录 GitHub，完成通过 GitHub OAuth App 的认证

6. 工具显示后，启用所需的工具

7. 如果希望从 Notion AI 调用时无需每次确认工具执行，请将执行设置改为 Run automatically

对 Agent 的指示

例如，在 Agent 的指示中添加如下内容，以确保在需要随机选择时必定使用 random-mcp。

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

认证

服务器在 /mcp 接受 Streamable HTTP 连接。与 MCP 客户端的授权使用 OAuth 2.1，用户的认证使用 GitHub OAuth。

授权时，在显示 MCP 客户端的访问许可画面后，会跳转到 GitHub 的认证画面。从 GitHub 获取的权限为 read:user。已授权的 MCP 客户端将获得带有 mcp:use 范围的访问令牌。

工具

random-mcp 提供以下4个工具，每个工具都要求包含所列字段的 JSON 对象。

random_int

生成指定范围内的一个整数。

• min: 最小值

• max: 最大值

参数示例：{"min": 5, "max": 10}

random_double

生成指定范围内的一个浮点数。

• min: 最小值

• max: 最大值

参数示例：{"min": 1.41421, "max": 3.14159}

random_choice

从候选项中选择一个元素。

• choices: 候选字符串数组。1个以上1,000个以下

• weights: 各候选项的相对权重。省略时等概率

指定 weights 时，需与 choices 的元素数量一致，且至少有一个为正数。

参数示例：{"choices":["A","B","C"],"weights":[1,2,1]}

random_sample

从指定的概率分布生成多个样本。

• distribution: 概率分布名称

• parameters: 按分布提供参数的字段名

• count: 样本数。1以上100以下，默认值为1

还有额外的计算量限制。

• 二项分布：trials 为0以上100,000以下的安全整数，且 trials * count <= 100000

• 泊松分布：lambda 为0以上100以下，且 lambda * count <= 10000

参数示例：{"distribution":"uniform","parameters":{"min":5,"max":15},"count":3}

开发环境

• Node.js 22.19.0 以上

• npm

• GitHub 账户

• Cloudflare 账户（部署时）

安装依赖。

npm install

本地开发

创建 GitHub OAuth App

在 GitHub 的 Developer settings 中创建 OAuth App。本地环境和生产环境的回调 URL 不同，因此需要分别创建不同的 OAuth App。

本地开发用 OAuth App 设置以下值。

• Homepage URL: http://localhost:8787

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

生产用 OAuth App 中，将 http://localhost:8787 部分替换为部署目标 Worker 的源。现有服务的回调 URL 为 https://random-mcp.eldesh-tools.workers.dev/callback。

创建后，获取 Client ID 和 Client secret。此应用向 GitHub 请求的 OAuth 范围为 read:user。

环境变量

在项目根目录下创建 .dev.vars。

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

COOKIE_ENCRYPTION_KEY 可以通过例如以下命令生成。

openssl rand -hex 32

OAuth 的临时 state 保存在 wrangler.jsonc 的 OAUTH_KV 绑定所指定的 Cloudflare KV 中。如果部署到其他 Cloudflare 账户，请创建 KV namespace，并将 wrangler.jsonc 中的 id 替换为该 namespace ID。

启动

启动本地服务器。

npm run dev

通常，MCP 端点为以下 URL。

http://localhost:8787/mcp

[!NOTE] 即使 Wrangler 显示无法获取 Request.cf 的警告，只要最后显示 Ready on http://localhost:8787，并且此项目未使用 Request.cf，就可以继续运行确认。

通过 MCP Inspector 进行运行确认

在本地服务器启动的状态下，启动 MCP Inspector 的 Web UI。

npx --yes @modelcontextprotocol/inspector@latest

在 Inspector 中选择 Streamable HTTP，并将连接目标指定为 http://localhost:8787/mcp。连接时会在浏览器中启动 OAuth 授权流程，因此请允许访问并完成 GitHub 认证。如果要确认生产环境，请将连接目标改为已部署的 MCP URL。

连接后，确认 Tools 画面中显示工具中列出的内容。

部署到 Cloudflare Workers

登录 Cloudflare。

npx wrangler login

将生产用 GitHub OAuth App 的认证信息和 Cookie 加密密钥注册为 Cloudflare Secret。

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

确认 GitHub OAuth App 的 Authorization callback URL 指向部署目标 Worker 的 /callback，并且 wrangler.jsonc 中的 OAUTH_KV 指向可用的 KV namespace。

部署。

npm run deploy

公开 URL 通常为以下格式。

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

[!IMPORTANT] .dev.vars 不会自动反映到 Cloudflare。生产 Worker 引用注册在 Cloudflare Secret 中的值。

许可证

以 MIT License 发布。