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.2333, 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 contains/regex. Lets you read logs even on a dedicated server whose LogOutput.log isn't reachable.

Register it with Claude Code (game can be launched after; the connector reconnects):

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

Examples

Use 127.0.0.1, not localhost — the server binds IPv4 loopback only, and localhost may resolve to IPv6 ::1 first (which isn't bound). This IPv4-only bind is intentional: it keeps the endpoint strictly local.

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'

Config

BepInEx/config/valheimmcp.yml (written with defaults on first run; parsed by the dependency-free MiniYaml reader):

server:
  host: 127.0.0.1          # loopback only — endpoint is unauthenticated
  port: 8731
  commandTimeoutMs: 15000

render:
  defaultSize: 768         # render_view size when 'size' is omitted
  minSize: 256
  maxSize: 1280

wait:
  defaultTimeoutMs: 120000 # wait_for_log timeout when 'timeoutMs' is omitted
  maxTimeoutMs: 600000
  heartbeatMs: 5000        # SSE progress heartbeat while a wait is pending

log:
  bufferCapacity: 2000     # in-memory ring of recent log lines retained for get_log
  defaultLines: 200        # get_log lines returned when 'maxLines' is omitted
  maxLines: 1000

# Access control for run_command (and POST /command). 'deny' always wins; if
# 'allow' is non-empty, ONLY matching commands run. Match by command name;
# trailing '*' is a prefix wildcard (e.g. "spawn*").
commands:
  allow: []
  deny: []

Install

From Thunderstore (recommended): install with r2modman or the Thunderstore Mod Manager. It pulls in the BepInEx pack automatically.

Manual: install BepInExPack_Valheim, then drop ValheimMCP.dll into BepInEx/plugins/ValheimMCP/. Launch the game once to generate BepInEx/config/valheimmcp.yml, then edit it if needed.

Build

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

Output lands directly in BepInEx/plugins/ValheimMCP/. The build paths in the .csproj assume a local Steam install and an r2modman profile named valheim-modding; override ValheimDir / R2ModmanProfile if yours differ.

Releasing

CI can't compile this — it needs Valheim's (non-redistributable) managed assemblies — so releases are built locally. The version lives in one place, <Version> in ValheimMCP.csproj: it flows into the assembly version, the generated PluginInfo constants (used by Plugin.cs / McpServer.cs), and the packaged manifest.json (synced by scripts/package.sh). Bump it there, add a CHANGELOG.md entry, then:

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

Upload the same zip to Thunderstore. The GitHub Actions workflow (.github/workflows/release.yml) can publish the release for you on a v* tag if you git add -f the built zip onto the tagged commit.

Status / roadmap

• Done: plain HTTP routes + native in-process MCP (/mcp), capturing synchronous console output. Usable via curl or as Claude Code MCP tools.
• Known limitation: output from commands that print asynchronously (coroutines, e.g. screenshot capture) is not captured — only what's printed synchronously during the call.
• Possible next: a GET /file route (and/or inlining written: <path> contents) so commands that dump to disk return their payload too; typed introspection tools for live game state.

License

MIT © 2026 myrcutio