ValheimMCP

ValheimMCP

A standalone BepInEx plugin that exposes a localhost HTTP endpoint for driving

Valheim's in-game console remotely and returning the console output directly in the

response. Built to give an agent (Claude Code) reproducible, scriptable access to game

state — e.g. running console commands like pos and reading what they print, without

typing into the in-game console or round-tripping through dump files.

⚠️ Security

This mod opens an unauthenticated HTTP endpoint that runs arbitrary Valheim

console commands (including anything devcommands unlocks). There is no token, no

password, no per-request check beyond the optional allow/deny list below.

• It binds IPv4 loopback (127.0.0.1) only by default, so it is not reachable

from other machines. Treat any change to server.host as exposing full console

control to whoever can reach that address — don't bind it to 0.0.0.0 or a LAN IP.

• Any process on your own machine can still drive the game while the listener is up.

If that matters to you, lock it down with the commands.allow / commands.deny

list (see Config) so only the commands you intend can run.

• This is a development/automation tool. Don't run it on a shared or public host.

Compatibility

Built and tested against Valheim (BepInEx pack

denikson-BepInExPack_Valheim-5.4.2350, BepInEx 5.4.x). It only depends on

Valheim's own Console/Terminal, so it should be resilient across game patches,

but it is not tied to any specific game build.

Design

• Ships into BepInEx/plugins/ValheimMCP/ (loaded once, not hot-reloaded), so the

listener stays up across F6 reloads of the mods you're iterating on and never fights

for its port.

• A background HttpListener thread accepts requests and marshals each onto Unity's

main thread (MainThreadDispatcher) before touching any Valheim API.

• Console output is captured with a Harmony postfix on Terminal.AddString while a

command runs — no private-field reflection.

• Zero dependency on any other mod: it drives Valheim's Console/Terminal, which

already has every registered command.

Routes

| Method | Path | Body / Query | Returns |

|--------|-------------|---------------------------|---------|

| POST | /mcp | JSON-RPC 2.0 (MCP) | MCP response (application/json) |

| GET | /health | — | {ok, inGame} |

| GET | /commands | — | {ok, commands:[{name,description}]} |

| POST | /command | raw command line, or?text= | {ok, ran, output:[...], error?} |

| GET | /log |?since=?maxLines=?contains=?regex= | {ok, cursor, matching, dropped, lines:[...]} |

| GET | /sse | — | 501 Not Implemented (no SSE transport) |

The plain /health, /commands, /command routes are for curl/scripting.

/mcp speaks the protocol Claude Code consumes.

MCP (native, no bridge)

The plugin implements the MCP Streamable-HTTP transport (JSON-RPC 2.0) directly,

with no external dependencies — a hand-rolled JSON parser/writer and stateless

application/json responses (no SSE). Tools:

• run_command(text) — run a console command, return captured output.
• list_commands() — all registered console commands.
• health() — is a world loaded.
• render_view(x, z, [y, yaw, pitch, dist, size]) — render the location with an

independent off-screen camera (never touches the player's view) and return

the PNG inline. The off-screen camera is named valheimmcp_render_cam, so a mod

that can draw debug overlays into a named camera can target it to render those

overlays into only this view, leaving the player's screen untouched.

• wait_for_log(pattern, [regex, timeoutMs]) — block until a log line matches,

then return it (streams observed lines as progress when the client sends a

progressToken). For waiting on an async event (e.g. a mod hot-reload finishing).

• get_log([since, maxLines, contains, regex]) — tail recent log lines from an

in-memory ring buffer (the MCP server, the game, and every other mod), returning

immediately. Omit since for the latest lines; pass back the cursor from the

result header to poll only what's new. Filter with con