rimworld-mod-mcp

mcp
Guvenlik Denetimi
Uyari
Health Uyari
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Gecti
  • Code scan — Scanned 7 files during light audit, no dangerous patterns found
Permissions Gecti
  • Permissions — No dangerous permissions requested

Bu listing icin henuz AI raporu yok.

SUMMARY

Local-only MCP server for RimWorld modding: search the game's Defs and C# API, decompile installed mods, build mods, and test them in an isolated game session. Works with Claude Code, Codex, and any MCP client.

README.md

rimworld-mod-mcp

M8ven Score
MCP
License: MIT

A local-only Model Context Protocol server that lets Claude Code, Codex, and other MCP clients research RimWorld's API and Defs, create and build mods, validate assets, and test them in an isolated game session.

This project is inspired by Modmixer but is an independent implementation: it contains no Modmixer source code, does not depend on Modmixer, and never communicates with Modmixer or any other external service.

This project contains no Steam Workshop publishing, uploading, or any external content transfer.

繁體中文

Highlights

  • Runs on Windows, macOS, and Linux; ships as a single self-contained executable (or a dotnet tool built from source).
  • Reads IL metadata directly to build the symbol index — roughly a hundred thousand symbols in seconds, with complete inheritance chains and real type signatures.
  • SQLite FTS5 full-text search over Defs, symbols, and decompiled source.
  • In-process decompilation via ICSharpCode.Decompiler. No external tools, no toolchain setup step.
  • Build failures return structured diagnostics (error code, file, line, column) instead of a wall of MSBuild output.
  • Tests mods with an isolated save folder and temporary directory links, leaving your real saves and settings untouched.
  • Merges diagnostics from the in-game bridge and Player.log. If the bridge cannot connect, Player.log still works and the reason is reported rather than silently degraded.
  • The bridge also reports in-game state (main menu vs. playing, map loaded, tick, paused, loading, open dialogs), so an agent can wait for the map to come up before judging a test instead of guessing from log silence.
  • The bridge ships as source and is built by run_test_cycle against your installed game's own assemblies.
  • Game files, decompiled output, indexes, and diagnostics all stay on your machine.

Requirements

  • A legitimately installed copy of RimWorld 1.7 (RimWorld 1.6 is not supported)
  • .NET SDK 10, for build_mod (compiling C# mods), for run_test_cycle (building the bridge), or for installing from source

[!NOTE]
The release executable is self-contained: running the server needs no .NET Runtime. The in-game bridge is embedded in the tool as source; run_test_cycle compiles it once against the RimWorld assemblies it detects (which needs the SDK) and reuses that build until the bridge or the game changes. Mod projects created by create_mod reference the RimWorld API through the Krafs.Rimworld.Ref NuGet package instead of the game's own assemblies; this repository itself contains no RimWorld binaries.

RimWorld 1.7 no longer runs on Unity: it runs on .NET 10 with its assemblies in the install root. The in-game bridge builds against those local assemblies, while create_mod C# projects target net10.0 and resolve the RimWorld API via the Krafs.Rimworld.Ref NuGet package.

Installation

Ask your agent to install it

If you use Claude Code, Codex, or another coding agent, you can hand the whole setup over. Paste this prompt:

Please install rimworld-mod-mcp for me, following https://github.com/mushroomTW/rimworld-mod-mcp (README.md).
Download the executable for my platform from the latest release, put it in a stable folder, and register it
as an MCP server named "rimworld" with the argument "stdio" in my MCP client. Then call rimworld_status
to confirm RimWorld was detected, and call rebuild_index once.

The agent downloads the file, registers it in your client's configuration, and verifies it. Restart or reload your MCP client afterwards if the new server does not appear.

Download a release (recommended)

Download the executable for your platform from the latest release:

Platform File
Windows x64 rimworld-mod-mcp-<version>-win-x64.exe
macOS (Apple Silicon) rimworld-mod-mcp-<version>-osx-arm64
Linux x64 rimworld-mod-mcp-<version>-linux-x64

That single file is the whole tool: no .NET Runtime is needed, and the in-game bridge is embedded in it (it is unpacked to the cache directory the first time run_test_cycle needs it). Put it anywhere and point your MCP client at it.

On macOS and Linux, mark the file as executable after downloading. macOS may also block it because it is not notarized; clear the quarantine flag once:

chmod +x rimworld-mod-mcp-*-osx-arm64
xattr -d com.apple.quarantine rimworld-mod-mcp-*-osx-arm64

From source

As a global dotnet tool:

dotnet pack src/RimWorldModMcp.Server -c Release -o ./nupkg
dotnet tool install -g RimWorldModMcp --add-source ./nupkg

Or as a self-contained single executable, the same way the releases are built:

# Windows (x64)
dotnet publish src/RimWorldModMcp.Server -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -p:EnableCompressionInSingleFile=true -o ./publish

# macOS (Apple Silicon)
dotnet publish src/RimWorldModMcp.Server -c Release -r osx-arm64 --self-contained true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -p:EnableCompressionInSingleFile=true -o ./publish

# Linux (x64)
dotnet publish src/RimWorldModMcp.Server -c Release -r linux-x64 --self-contained true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -p:EnableCompressionInSingleFile=true -o ./publish

Note: The publish output also contains a bridge/ directory. The executable does not need it (the bridge is embedded), but when it is present next to the executable it takes precedence over the embedded copy.

MCP client configuration

Point the command at the executable you downloaded — see local-build.mcp.json:

{
  "mcpServers": {
    "rimworld": {
      "command": "C:\\path\\to\\rimworld-mod-mcp-<version>-win-x64.exe",
      "args": ["stdio"]
    }
  }
}

On macOS and Linux, use the absolute path to the downloaded file instead. When installed as a dotnet tool from source, rimworld-mod-mcp is on your PATH, so no absolute path is needed:

{
  "mcpServers": {
    "rimworld": {
      "command": "rimworld-mod-mcp",
      "args": ["stdio"]
    }
  }
}

create_mod, build_mod, and run_test_cycle accept any local directory path; there is no write boundary — scoping writes is left to your MCP client's permission prompts and to you.

Templates live in examples/: Claude Code, Codex, custom port and game path.

First use

  1. Configure the server in your MCP client.
  2. Call rimworld_status to confirm RimWorld was detected.
  3. Call rebuild_index once. Def and symbol indexing finishes in seconds and is immediately usable; the source-code full-text index continues in the background, and search_source reports source_indexed: false until it completes.

Tools

Researching the game

Tool Purpose
rimworld_status Detected paths and index state. index.source_index says whether the source full-text layer is running, failed (error), or done.
rebuild_index Rebuild the Def and symbol indexes.
search_defs Search Defs by name, label, or description.
read_def Read one Def's full XML. Look up abstract Defs by their Name attribute.
read_symbol Signature, full inheritance chain, and interfaces for a symbol; optionally decompiled source. Exact name matches win: when any exist, substring matches are left out and counted in partial_count. assembly narrows to one assembly (or one version of a multi-version mod). Zero hits return suggestions.
list_symbols Browse without a keyword: a namespace lists its top-level types and child namespaces; a type lists its members. An unknown parent is an error, not an empty list.
find_descendants Find every class deriving from a given type; a short name works when unambiguous. Zero hits return suggestions.
search_source Regex search (.NET syntax, always case-insensitive) over decompiled source: the game by default, or one installed mod with package_id (first use decompiles in the background; indexing=true means retry shortly). assembly (e.g. 1.7/) restricts a mod search to one version's DLL. Prefer simple literals (CurTimeSpeed); `a
read_source_file Read a whole decompiled file (game or mod) by the assembly and file a search returned, paging by line (start_line + max_bytes). Check source_indexed before trusting empty results.
find_def_usages Find where a Def is referenced, across XML cross-references and C# DefOf fields. Use it to verify translatable fields before hand-writing Languages/ XML.

Installed mods

Tool Purpose
list_installed_mods List local and Workshop mods. Filter with package_id and page with limit/offset; include_details adds the path, dependencies and versions.
inspect_installed_mod Decompile and index a mod's assemblies on demand. Locks are per-packageId, so a large mod (minutes on first run) does not block other mods. Each assembly is keyed mod:<packageId>:<relative DLL path>, e.g. mod:cj.rimtalk:1.7/Assemblies/RimTalk.dll.

Build

Tool Purpose
create_mod Create a mod skeleton, optionally with a C# project whose csproj already references the RimWorld API via the Krafs.Rimworld.Ref NuGet package.
build_mod Validate an XML mod, or build a C# mod and deploy its DLL; compiler errors come back as structured diagnostics.

The tool set deliberately covers only what an AI coding agent cannot do on its own: querying Defs and decompiled source from the game and other mods, building, and launching the game in an isolated test session. Copying files, creating directories, and snapshots are things the agent already does natively, so no tools are provided for them — use Git for version control.

Testing and diagnostics

Tool Purpose
run_test_cycle Launch RimWorld in an isolated session to test a mod. Use it for in-game acceptance (time-speed feel, rendering) that static analysis cannot cover.
test_status Current session state: whether the bridge and daemon are healthy, and game, the in-game state the bridge last reported (program_state Entry/MapInitializing/Playing, map_loaded, tick, paused, time_speed, loading, open_windows, colonists, age_ms). Pass wait_for_state=Playing to block until the map is up.
stop_test Stop the session and clean up; requires confirm: true.
list_test_diagnostics List collected errors and warnings. Poll with since_at (the previous latest_at) and wait_seconds to long-poll for new entries instead of re-reading the list.
get_test_diagnostic Fetch one diagnostic in full by hash.

The three indexing tiers

Indexing is deliberately layered so the most useful data is ready first:

Tier Contents Cost
1 Def XML and IL metadata symbols Seconds; the bulk of rebuild_index
2 Single-member decompilation Milliseconds, computed on demand by read_symbol
3 Full-assembly decompiled source, full-text indexed Minutes, runs in the background

Once tier 1 completes, Def search, symbol lookup, inheritance chains, and read_symbol all work. Only search_source waits on tier 3.

How test sessions stay isolated

  • -savedatafolder points at a temporary directory, so your real saves and settings are untouched.
  • A generated ModsConfig.xml activates only the mod under test and its dependencies, carrying over your existing game version and known DLC.
  • Temporary links in the Mods folder point at your workspace, so edits take effect without copying files. Windows uses junctions (no administrator rights needed); macOS and Linux use symbolic links.
  • By default run_test_cycle adds -headless -NoCrashDialog (RimWorld 1.7), so no game window is created; the bridge still reports state and errors. Pass headless=false to show the window.
  • Starting a test is refused while the game is already running — it would interfere with your own save.
  • Stopping a session removes the links, terminates the daemon, and cleans up the temporary save data. Link removal never recurses into the target, so your mod source is never touched.

What the agent can see during a test

The bridge is a small Harmony mod, active only when a session token is present. It pushes two kinds of data over loopback using .NET 10's built-in System.Text.Json (Utf8JsonWriter) with thread-static buffers for zero-allocation streaming without external DLL dependencies:

  • Diagnostics: every Log.Error / Log.Warning, deduplicated with occurrence counts; when the diagnostics daemon is unavailable, they fall back to Player.log.
  • Game state (about once a second, or every 5 s as a heartbeat): program_state, whether a map is loaded, tick, paused, time speed, whether a long load is running, the open window types (a Dialog_* here usually means something is blocking), colonist count, and game version. test_status returns the latest report with its age.

No screenshots: coding agents typically have their own screen-capture tooling, and this server stays focused on what they cannot do alone.

Compared with similar projects

There are several AI-modding tools for RimWorld. They mostly occupy different niches; this table is from each project's README and repository as of September 2026 and only lists what those sources state.

rimworld-mod-mcp Modmixer RimSage RimBridgeServer RiMCP_hybrid
Form MCP server (single dotnet tool / executable), bring your own agent Electron desktop app with a built-in agent; you supply a model API key MCP server (Bun + ripgrep); hosted at mcp.rimsage.com or self-hosted In-game mod exposing a tool bridge; used through GABS or a direct connection MCP server (C#, Lucene + vector + graph RAG)
Game API research IL metadata symbol index in seconds; per-member decompilation on demand; full-text source in the background Decompiles game and DLC assemblies with a vendored ilspycmd, then indexes Yes, but you decompile the game yourself first (import-csharp takes a decompiled source tree) No Yes, but you decompile the game yourself first (ILSpy or dnSpy output placed in RimWorldData/); requires an embedding model (local or remote API) to build the index
Def XML search Yes, with cross-reference lookup (find_def_usages) Yes Yes (search_defs, get_def_details) No Yes
Installed mods List, decompile and search other mods' assemblies Lists local and Workshop mods, edits the active list and load order, flags missing dependencies, incompatibilities and load-order problems; indexes only game/DLC assemblies, decompiles other DLLs on demand (decompile_dll) No List mods, read/change mod settings and load order in the running game No
Build C# build with structured compiler diagnostics Yes (agent edits and builds) No No No
Test launch Isolated save folder, generated ModsConfig.xml, junction/symlink to your workspace Launches the game with the mod installed; bridge mod watches for errors No Starts a debug game or loads a save through GABS No
In-game feedback Errors/warnings + game state (scene, map, tick, paused, open dialogs) Errors via its bridge mod No Full live state, semantic UI layout, screenshots, debug actions, Lua scripting No
Steam Workshop None by design Publishing built in No No No
Network Local (loopback only; first build may restore one NuGet reference package) Model provider API, Workshop upload; ships @sentry/electron Hosted mode sends queries to rimsage.com; self-hosted mode is local Local Local unless a remote embedding API is used
License MIT MIT MIT MIT MIT

Where this project fits:

  • Versus Modmixer: same overall loop (research → build → launch → read errors), but as a headless MCP server for coding agents you already use (Claude Code, Codex, …) rather than a desktop app with its own chat. No Workshop publishing and no art/audio pipeline. Indexing is layered so symbol lookup works within seconds of the first rebuild_index instead of waiting for a full decompile.
  • Versus RimSage / RiMCP_hybrid: those are research-only. This server also decompiles for you, builds, and tests; RiMCP_hybrid's semantic search may find conceptually related code that a literal/regex search misses.
  • Versus RimBridgeServer: complementary rather than competing. RimBridgeServer gives an agent deep control of a running game (UI, screenshots, debug actions); this project's bridge reports only diagnostics and coarse game state. Use RimBridgeServer when you need in-game interaction; use this server for the API research, build, and isolated launch around it.

Security and privacy

  • The only tools that write files are create_mod, build_mod, and run_test_cycle, and they write only to the mod directory you pass (test sessions additionally use an isolated temporary save directory). There is no path allow-list; rely on your MCP client's tool-permission prompts.
  • No external network communication by the server itself (initial C# mod builds may restore reference packages from NuGet). Game files, decompiled output, indexes, and diagnostics stay local.
  • The bridge activates only when RIMWORLD_MOD_MCP_BRIDGE_TOKEN is present and connects only to 127.0.0.1. Each test session uses a single-use token; the token is never written to diagnostic records and never appears in tool responses.
  • Destructive operations (stop_test) require an explicit confirm: true.

Environment variables

Variable Purpose
RIMWORLD_MOD_MCP_GAME_PATH Override RimWorld installation detection.
RIMWORLD_MOD_MCP_PLAYER_LOG Override the Player.log location.
RIMWORLD_MOD_MCP_BRIDGE_PORT Loopback port for the diagnostics daemon; defaults to 49460.
RIMWORLD_MOD_MCP_PERF_MARKERS Extra markers, separated by |. A Log.Message containing [perf] or any extra marker is recorded as a performance diagnostic (query with list_test_diagnostics(type=performance)).
RIMWORLD_MANAGED_DIR Directory containing game assemblies (Assembly-CSharp.dll and UnityStubs.dll). Injected automatically for bridge builds and legacy mod projects; can be set manually for command-line builds.

Development

dotnet build RimWorldModMcp.slnx
dotnet test RimWorldModMcp.slnx

CI runs the platform contract tests on Windows, macOS, and Ubuntu — junction behaviour and process liveness semantics differ per platform, so verifying on only one would lose the protection they provide.

Development subcommand (not part of the tool listing, useful for troubleshooting):

dotnet run --project src/RimWorldModMcp.Server -- detect      # show detected paths

License

MIT, see LICENSE.

Yorumlar (0)

Sonuc bulunamadi