用于远程驱动英灵神殿控制台并读取输出的本地主机HTTP/MCP端点。专为代理驱动（Claude Code）访问游戏状态而构建。

瓦尔海姆MCP

一个独立的BepInEx插件，用于公开一个 本地主机 HTTP 端点 用于远程驱动《英灵神殿》游戏内控制台，并直接在响应中返回控制台输出。旨在为代理（Claude Code）提供可复现、可脚本化的游戏状态访问方式——例如运行以下控制台命令 位置 并读取它们打印的内容，而无需在游戏内控制台中输入命令，也无需通过转储文件来回操作。

⚠️ 安全

这个模组打开了一个 未认证 运行所用的HTTP端点 任意英灵神殿控制台命令 （包括任何 开发者命令 解锁）。没有令牌，没有密码，除了下面可选的允许/拒绝列表外，没有按请求的检查。

• 它束缚着 IPv4 环回（127.0.0.1仅 默认情况下，因此无法从其他机器访问。对以下任何更改都应谨慎对待 服务器主机 将完整控制台权限暴露给任何能访问该地址的人——不要将其绑定到 0.0.0.0 或局域网IP。
• 监听器开启时，你自己机器上的任何进程仍然可以驱动游戏。如果这对你很重要，请用以下方式锁定它： 允许 / 拒绝命令 列表（见 配置因此只有你打算执行的命令才能运行。
• 这是一个开发/自动化工具。请勿在共享或公共主机上运行。

兼容性

基于以下环境构建并测试： 英灵神殿 (BepInEx整合包 denikson-BepInExPack_Valheim-5.4.2350，BepInEx 5.4.x）。它仅依赖于 Valheim 自身的 控制台/终端，因此它应能在游戏补丁更新后保持兼容，但它不与任何特定的游戏版本绑定。

设计

• 出货至 BepInEx/plugins/ValheimMCP/ （仅加载一次， 不 热重载），因此监听器在你迭代的模组进行F6重载期间会一直保持运行，并且永远不会争抢端口。
• 一个背景 HTTP监听器 线程接受请求并将每个请求调度到Unity的主线程（主线程调度器在接触任何英灵神殿 API 之前）。
• 已启用Harmony后缀，正在捕获控制台输出 终端.添加字符串 当命令运行时——不进行私有字段反射。
• 完全独立于任何其他模组：它驱动瓦尔海姆的 控制台/终端，它已经拥有所有已注册的命令。

路线

方法	路径	身体/查询	返回
发布	/mcp	JSON-RPC 2.0（MCP）	MCP响应（application/json)
获取	生命值	—	{确认，游戏中}
获取	/commands	—	{ok, commands:[{name,description}]}
帖子	/命令	原始命令行，或 ？文本=	{ok, ran, output:[...], error?}
获取	/log	自 ?maxLines= 包含= ？regex=	{ok, cursor, matching, dropped, lines:[...]}
获取	/南南东	—	501 未实现 （无SSE传输）

平原 生命值, /commands, /command 路线用于 卷曲/脚本。 /mcp 说出 Claude Code 所采用的协议。

MCP（原生，无桥接）

该插件直接实现了MCP Streamable-HTTP传输（JSON-RPC 2.0），无外部依赖——手写的JSON解析器/写入器且无状态 应用程序/JSON 回复（无服务器发送事件）。工具：

• 运行指令(文本) — 运行控制台命令，返回捕获的输出。
• 列出命令() — 所有已注册的控制台命令。
• 生命值() —世界已加载。
• 渲染视图(x, z, [y, 偏航角, 俯仰角, 距离, 尺寸]) ——渲染该位置，使用一个 独立画外摄像机 （从不接触玩家视图）并以内联方式返回 PNG。离屏相机名为 瓦尔海姆渲染镜头，因此，一个能够将调试叠加层绘制到指定摄像机的模组，可以将目标对准它，从而将这些叠加层渲染到 仅 这个视角，不会影响玩家的屏幕画面。
• 等待日志(pattern, [regex, timeoutMs]) — 阻塞直到某条日志行匹配，然后返回该行（当客户端发送 progressToken 时，将观察到的日志行作为进度流式输出）。用于等待异步事件（例如某个模组热重载完成）。
• get_log([since, maxLines, contains, regex]) — 从内存环形缓冲区中读取最近的日志行（MCP服务器、游戏以及其他所有模组），立即返回。省略 自从 获取最新台词；传回 光标 从结果头部仅轮询新增内容。使用以下条件筛选： 包含/正则表达式。让你即使在专用服务器上也能读取日志，该服务器 日志输出.log 无法到达。

将其注册到Claude Code（之后即可启动游戏；连接器会重新连接）：

claude mcp add --transport http valheim http://127.0.0.1:8731/mcp

示例

使用 127.0.0.1，不是 本地主机 — 服务器仅绑定 IPv4 回环地址，且 本地主机 可能解析为IPv6 ::1 首先（未绑定）。此仅限IPv4的绑定是有意为之：它使端点严格保持本地。

curl -s 127.0.0.1:8731/health curl -s 127.0.0.1:8731/commands curl -s -X POST 127.0.0.1:8731/command --data 'pos'

配置

BepInEx/配置/valheimmcp.yml （首次运行时以默认值写入；由无依赖的 迷你YAML 读者）：

服务器：主机：127.0.0.1 # 仅限回环地址——该端点未进行身份验证 端口：8731 commandTimeoutMs：15000 render：defaultSize：768 # 省略“size”时render_view的大小 minSize：256 maxSize：1280 wait：defaultTimeoutMs：120000 # 省略“timeoutMs”时wait_for_log的超时时间 maxTimeoutMs：600000 heartbeatMs：5000 # 等待挂起期间的SSE进度心跳 log：bufferCapacity：2000 # 为get_log保留的近期日志行的内存环形缓冲区 defaultLines：200 # 省略“maxLines”时get_log返回的行数 maxLines：1000 # run_command（以及POST /command）的访问控制。“deny”始终优先；如果 # “allow”非空，则仅匹配的命令会运行。按命令名称匹配； # 末尾的“*”是前缀通配符（例如“spawn*”）。 commands：allow：[] deny：[]

安装

来自Thunderstore（推荐）： 使用以下方式安装 r2modman 或Thunderstore模组管理器。它会自动引入BepInEx包。

手动： 安装 BepInExPack_Valheim然后掉落 ValheimMCP.dll 进入 BepInEx/plugins/ValheimMCP/. 启动游戏一次以生成 BepInEx/配置/valheimmcp.yml，然后根据需要编辑它。

建造

dotnet build src/ValheimMCP/ValheimMCP.csproj -c Release

直接输出到 BepInEx/plugins/ValheimMCP/。构建路径在 项目文件 假设本地已安装 Steam，并且有一个名为 瓦尔海姆模组制作; 覆盖 瓦尔海姆目录 / R2Modman配置 如果你的不同。

释放

CI 无法编译这个——它需要 Valheim 的（不可再分发的）托管程序集——所以发布版本是在本地构建的。版本号位于 一个地方, <版本> 在……里 ValheimMCP.csproj：它流入汇编版本，生成 插件信息 常量（由使用 插件.cs / McpServer.cs)，以及打包好的 manifest.json （由以下同步 脚本/包.sh)。碰一下那里，加一个 更新日志.md 然后输入：

./scripts/package.sh # -> dist/ValheimMCP-<version>.zip gh release create v<version> dist/ValheimMCP-<version>.zip --generate-notes

将同一个zip文件上传至 雷霆商店. GitHub Actions 工作流（.github/workflows/release.yml) 可以为你发布版本，在 v* 如果你 git add -f 将构建好的 zip 放到标记的提交上。

状态 / 路线图

• 完成： 纯HTTP路由 + 原生进程内MCP（/mcp），捕获同步控制台输出。可通过以下方式使用 卷曲 或者作为Claude Code MCP工具。
• 已知限制： 异步打印输出的命令（协程，例如截图）不会被捕获——只会捕获调用期间同步打印的内容。
• 可能的下一步： a GET /file 路线（和/或内联 编写：<path> 内容），因此转储到磁盘的命令也会返回其有效载荷；用于实时游戏状态的类型化内省工具。

授权

麻省理工学院 © 2026 myrcutio