5e-mcp（Solo D&D 5e MCP Server）

一句话定位：D&D 5e 规则引擎（MCP Server）——「AI 讲故事、服务器管规则」，掷骰/HP/先攻/法术位/金币全部由代码保证，解决 LLM 数值幻觉；无需任何 API key。类型：MCP 工具服务器 · 开源 · 仓库：gwyntel/5e-mcp · 作者：Gwyneth & Gemini 3 Pro & GLM 4.6（AI 辅助开发）

1. 项目概述

2025 年「MCP 化 GM」浪潮的代表作。它的设计哲学直击 AI 跑团的痛点：LLM 掷骰不可信、数值不可信。所以把 D&D 5e 的规则全部实现为确定性代码工具，挂到任意支持 MCP 的 AI 客户端（Claude Desktop 等）上——AI 负责叙事与裁决，服务器负责所有机械规则与状态持久化。玩家角色、金币、背包、战役进度自动存档，关掉聊天明天继续。

2. 核心功能（42 个 DM 工具，实测全部可用）

掷骰：roll_dice（XdY+Z 表达式 + 优劣势双掷）、roll_initiative、死亡豁免。
角色：create_character（种族/职业/背景/六维/等级/生命骰）、角色卡查询、HP 增减（自动处理濒死）、休整/生命骰、状态（condition）管理、经验值（自动升级检测）、AC/熟练加值/属性调整值计算。
背包与经济：物品增删/装备/卸下、金币账本、负重。
战斗：先攻开战、全体先攻、回合推进、攻击结算、结束战斗。
法术：法术位管理、施法；查询：怪物/SRD 法术/物品/专长/随机怪物。
生成器：怪物 stat block、魔法物品卡、地点描述（结构化 JSON）。
战役状态：get_campaign_state / update_campaign_state（多战役并行存档）。
Prompt：内置 dnd_dm 系统提示词，一键让 AI 进入 DM 角色。

3. 技术架构

FastMCP（Python）注册 42 个 @tool；数据模型为 Pydantic（角色卡/怪物/物品均为强类型 JSON）。
持久化默认本地存储（支持 Redis 后端；default 战役在 Redis 下受限）。
传输默认 stdio；本机实测通过 20 行 wrapper 切换 Streamable HTTP（:8931/mcp）绕过沙箱管道限制。
依赖极轻：fastmcp / pydantic / httpx / py-key-value-aio（4 个包）。

4. 本机实测记录（✅ 42 工具全流程）

initialize → 服务「Solo D&D 5e Server」；tools/list → 42 工具。
实测样例：
- create_character → 3 级人类战士 Garrick（HP 28 / AC 11），角色卡含熟练加值、生命骰、豁免、技能表、负重 240 磅；
- roll_dice("2d6+3") → [1,4]+3 = 8；roll_dice("1d20+5", advantage) → 双掷取高 17；
- generator_monster_tool → 哥布林完整 stat block（含 Nimble Escape 特性）；
- generator_item_tool → +1 稀有长剑（暴击附加 1d6 火焰）完整道具卡；
- add_gold(50) → 金币账本更新；get_character_sheet → 完整角色卡 JSON。
踩坑：MCP streamable-http 会话头必须随请求携带，否则 tools/call 返回空。

5. 如何运行（复现）

git clone https://github.com/gwyntel/5e-mcp && cd 5e-mcp
python -m venv .venv && .venv\Scripts\pip install -r requirements.txt
python -m dnd_mcp_server.server          # stdio，挂到 Claude Desktop 等 MCP 客户端
# 或 HTTP 传输（本机沙箱用）：
# mcp.run(transport='streamable-http', host='127.0.0.1', port=8931)

配合 system_prompt.md（或 MCP prompt dnd_dm）粘贴给 AI 客户端即可开始单人跑团。

6. 优劣势分析

优势	劣势
零 API key、纯规则引擎可独立运行	仅 D&D 5e（无 CoC 等其他规则）
规则正确性 100% 由代码保证	叙事仍依赖外部 LLM（客户端）
42 工具覆盖建卡→战斗→成长全流程	单人跑团为主，无多人社交机制
MCP 协议 = 任意 AI 客户端即插即用	项目年轻（2025 年），生态刚起步

7. 参考链接

仓库：https://github.com/gwyntel/5e-mcp
同类 MCP 项目：mnehmos.rpg.mcp（npm）、matluz1/lorekit（MCP TTRPG 引擎）、CardoPixel/grimoire-dnd-vtt（Gemini 驱动 D&D VTT）