random-mcp

random-mcp

这是一个运行于 Cloudflare Workers 上的随机数生成 MCP（Model Context Protocol）服务。通过 Notion Agent 等 MCP 客户端，可以生成整数、浮点数、加权选择结果以及各种概率分布的样本。

官方网站：https://random-mcp.eldesh-tools.workers.dev/

目的

本项目旨在让用户能够将外部随机数生成处理作为 MCP 工具调用，而不是让语言模型自行选择随机数。

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

随机数源使用 Web Crypto API。整数生成采用拒绝采样，以避免取模造成的偏差。不过，本 API 并非用于生成加密密钥或认证令牌。

使用官方服务

官方服务可通过以下 MCP 端点使用。用户无需配置 Cloudflare 或 GitHub OAuth App。

https://random-mcp.eldesh-tools.workers.dev/mcp

连接到 Notion AI

1. 选择 Settings > Connections > MCP > Custom MCP
2. 在 MCP server URL 中指定 https://random-mcp.eldesh-tools.workers.dev/mcp。如果使用自有实例，请指定其部署 URL
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 提供以下 3 个工具，每个工具都需要一个包含所列字段的 JSON 对象。

random_int

生成指定数量、符合指定概率分布的整数，并通过 values 数组返回。

• distribution：概率分布名称。省略时默认为 uniform
• count：生成数量。范围为 1 到 1,000，默认值为 1

distribution	附加字段	含义和限制
uniform	min, max	min 到 max（含边界）的整数均匀分布
bernoulli	probability	以指定概率取 1，否则取 0
binomial	trials, probability	二项分布。进行 trials 次相互独立的试验，每次成功概率为 probability，返回成功次数
poisson	lambda	参数为 lambda 的泊松分布

参数组合有以下限制：

• 二项分布：trials 必须是 0 到 100,000 之间的安全整数，且 trials * count <= 100000
• 泊松分布：lambda 必须在 0 到 100 之间，且 lambda * count <= 10000

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

random_double

生成指定数量、符合指定概率分布的浮点数，并通过 values 数组返回。

• distribution：概率分布名称。省略时默认为 uniform
• count：生成数量。范围为 1 到 1,000，默认值为 1

distribution	附加字段	含义和限制
uniform	min, max	半开区间 [min, max) 上的连续均匀分布
normal	mean, standard_deviation	指定均值和标准差的正态分布
lognormal	mu, sigma	对数正态分布，其中 log(X) 服从均值为 mu、标准差为 sigma 的正态分布
exponential	rate	速率为 rate 的指数分布。rate > 0

参数示例：{"distribution":"normal","mean":0,"standard_deviation":1,"count":20}

random_choice

从候选项中选择指定数量的元素，并通过 values 数组返回。

• choices：候选字符串数组。数量为 1 到 1,000
• weights：各候选项的相对权重。省略时按等概率处理
• count：选择数量。范围为 1 到 1,000，默认值为 1
• with_replacement：有放回抽样时为 true，无放回抽样时为 false。默认值为 true

指定 weights 时，其元素数量必须与 choices 一致，且至少有一个正值。 无放回抽样时，count 必须小于或等于候选项数量。指定权重时，count 还必须小于或等于权重为正的候选项数量。

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

本地开发

环境要求

• Node.js 22.19.0 或更高版本
• npm
• GitHub 账户

安装依赖项。

npm install

创建本地开发用 GitHub OAuth App

在 GitHub 的 Developer settings 中创建用于本地开发的 OAuth App。

设置以下值。

• Homepage URL：http://localhost:8787
• Authorization callback URL：http://localhost:8787/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 の暗号化に使用するランダムな値>
GLAMA_MAINTAINER_EMAIL=<Glamaアカウントのメールアドレス>

GLAMA_MAINTAINER_EMAIL 是可选设置，用于检查 /.well-known/glama.json 的响应内容。如果不在本地进行此项检查，可以省略。

COOKIE_ENCRYPTION_KEY 可以使用以下命令生成。

openssl rand -hex 32

如果更改了 wrangler.jsonc 中的绑定、兼容日期、兼容标志，或 .dev.vars 中的变量名，请更新 Workers 运行时和环境变量的类型定义。

npm run types

生成的 worker-configuration.d.ts 会提交到仓库。运行 npm run typecheck 可以确认类型定义与配置一致。

启动

启动本地服务。

npm run dev

MCP 端点通常为以下 URL。

http://localhost:8787/mcp

可通过 http://localhost:8787/ 查看首页。

说明

如果 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 页面显示了工具中列出的工具。

重要

截至 2026/08/20，MCP Inspector 不会为 random_int、random_double 推导出与输入类型对应的 Web UI 表单。 如果要验证这些工具的功能，请使用 MCP Inspector CLI 等工具。

构建自定义实例

本章介绍如何在 Cloudflare Workers 上构建 random-mcp 的新自定义实例。官方服务的部署不会使用这些步骤。

构建需要 Cloudflare 账户和用于生产环境的 GitHub OAuth App。由于本地环境和生产环境的回调 URL 不同，请为每个环境分别创建 OAuth App。

创建用于生产环境的 GitHub OAuth App

在 GitHub 的 Developer settings 中创建 OAuth App，并设置以下值。

• Homepage URL：部署目标 Worker 的源
• Authorization callback URL：在部署目标 Worker 的源后加上 /callback 的 URL

例如，如果 Worker 的源为 https://random-mcp.example.workers.dev，则 Authorization callback URL 为 https://random-mcp.example.workers.dev/callback。

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

配置 Cloudflare 资源和 Worker

创建 Cloudflare KV namespace，用于保存 OAuth 临时 state。接着，在 wrangler.jsonc 中为自定义实例修改以下项目。

• name：Worker 的名称
• kv_namespaces 中 OAUTH_KV 绑定项的 id：所创建 KV namespace 的 ID

注册 Secret

登录 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

与本地开发相同，COOKIE_ENCRYPTION_KEY 应使用随机值。.dev.vars 不会自动同步到 Cloudflare，因此必须将生产 Worker 使用的值注册为 Cloudflare Secret。

部署

确认 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

部署后，通过 MCP 客户端或 MCP Inspector 连接到公开 URL，并确认 GitHub OAuth 授权和工具调用正常。

发布官方服务

官方服务通过 Cloudflare 的 Git 集成进行部署。推送到 release 分支会触发自动部署，因此发布官方环境时请勿使用 npm run deploy。

维护人员请参阅 RELEASE.md 中的操作步骤。

许可证

根据 MIT License 发布。