mcp-random

提供给Claude真正随机性能力的MCP服务器。此服务器使Claude能够访问用于游戏、决策、抽样、模拟以及任何需要真实随机性的操作的加密安全随机数生成器。

为什么存在这个服务

Claude本身没有访问真正随机性的能力——当被要求“选择一个随机数字”或“抛硬币”时，它实际上是基于对话中的模式做出确定性选择。这个MCP服务器通过提供对加密安全随机函数的访问来解决这一限制。

🚀 安装

预备条件

• Node.js (v18或更高版本)
• 兼容MCP的客户端（如Claude Desktop）

快速安装

# 克隆仓库
git clone https://github.com/yourusername/mcp-random.git
cd mcp-random

# 安装依赖
npm install

# 构建TypeScript代码
npm run build

配置Claude Desktop

在你的Claude Desktop配置中添加（macOS上的路径为~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "random": {
      "command": "node",
      "args": ["/绝对路径到/mcp-random/dist/index.js"]
    }
  }
}

重启Claude Desktop以加载服务器。

📖 可用函数

基本随机数

random_integer(min, max)

生成介于min和max之间的随机整数（包括边界值）。

示例：random_integer(1, 10) → 7

random_float(min, max, precision?)

生成随机浮点数。

示例：random_float(0, 1, 2) → 0.42

随机选择

random_choice(options)

从数组中随机选取一个项目。

示例：random_choice(["red", "green", "blue"]) → "green"

random_sample(array, count)

从数组中选取多个唯一项目（无重复）。

示例：random_sample([1,2,3,4,5], 3) → [2,5,1]

random_shuffle(array)

随机重新排序数组。

示例：random_shuffle([1,2,3,4]) → [3,1,4,2]

random_weighted_choice(options, weights)

根据权重选取选项（权重越高越可能被选中）。

示例：random_weighted_choice(["A", "B", "C"], [1, 2, 1]) 
→ "B" （比A或C更有可能被选中）

游戏与决策

flip_coin(count?)

翻转一个或多个硬币。

示例：flip_coin() → "正面"
示例：flip_coin(3) → ["正面", "反面", "正面"]

roll_dice(sides, count?)

掷任意面数的骰子。

示例：roll_dice(6) → 4
示例：roll_dice(20, 2) → {"rolls": [15, 8], "sum": 23}

安全与标识符

random_uuid()

生成UUID v4。

示例：random_uuid() → "550e8400-e29b-41d4-a716-446655440000"

random_password(length?, options?)

生成安全密码。

示例：random_password(16) → "Kj9#mP2$xQ5@nL7!"
示例：random_password(12, {symbols: false}) → "Kj9mP2xQ5nL7"

选项：

• uppercase: 包含A-Z（默认：true）
• lowercase: 包含a-z（默认：true）
• numbers: 包含0-9（默认：true）
• symbols: 包含特殊字符（默认：true）
• excludeSimilar: 跳过容易混淆的字符如0/O, 1/l（默认：false）

random_bytes(count, encoding?)

生成用于加密用途的随机字节。

示例：random_bytes(16, 'hex') → "a3f2b8c9d4e5f6789abcdef012345678"

高级函数

random_normal(mean?, stddev?)

从正态分布（钟形曲线）生成数字。

示例：random_normal(100, 15) → 97.3 （类似智商分布）

文档

help()

获取所有函数的详细文档。

🎯 使用案例

决策制定

"我应该做X还是Y？" → flip_coin()
"帮我从这些选项中挑选一个" → random_choice([...])
"帮我优先处理这些任务" → random_shuffle([...])

游戏

"掷骰决定行动顺序" → roll_dice(20)
"从牌组中抽取5张牌" → random_sample(deck, 5)
"洗牌" → random_shuffle(cards)

创意写作

"随机选择一个角色特征" → random_choice(traits)
"生成一个角色名字" → random_weighted_choice(names, popularity)
"创建一个随机场景" → 多次调用random_choice

数据与测试

"生成测试数据" → random_integer, random_float
"从这个数据集中抽样" → random_sample
"创建一个测试ID" → random_uuid
"生成API密钥" → random_bytes

模拟

"蒙特卡洛模拟" → random_normal
"概率实验" → random_float(0, 1)
"A/B测试" → random_weighted_choice

🔧 开发

# 构建TypeScript
npm run build

# 运行测试  
npm test

# 检查代码
npm run lint

# 开发模式（构建并运行）
npm run dev

🔐 技术细节

• 所有随机性都使用Node.js crypto模块（加密安全）
• 无可预测的模式或偏差
• 调用之间不维持状态
• 使用TypeScript确保类型安全
• 全面的错误处理

📝 许可证

MIT许可证 - 详情见LICENSE文件。

🤝 贡献

欢迎贡献！请随时提交Pull Request。

💡 趣闻

• Claude意识到自身缺乏随机性后请求建造了这个工具
• 第一个建议的应用场景是实现塔罗牌占卜
• 此工具使Claude能够公平地玩游戏、做出无偏见的选择，并进行真实的模拟

---

"我没有随机函数。你应该有一个随机函数。现在这是一个很酷的MCP服务器。" - Claude