rimworld-mod-mcp
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.
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.
rimworld-mod-mcp
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.logstill 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_cycleagainst 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), forrun_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_cyclecompiles 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 bycreate_modreference the RimWorld API through theKrafs.Rimworld.RefNuGet 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
- Configure the server in your MCP client.
- Call
rimworld_statusto confirm RimWorld was detected. - Call
rebuild_indexonce. Def and symbol indexing finishes in seconds and is immediately usable; the source-code full-text index continues in the background, andsearch_sourcereportssource_indexed: falseuntil 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
-savedatafolderpoints at a temporary directory, so your real saves and settings are untouched.- A generated
ModsConfig.xmlactivates 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_cycleadds-headless -NoCrashDialog(RimWorld 1.7), so no game window is created; the bridge still reports state and errors. Passheadless=falseto 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 toPlayer.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 (aDialog_*here usually means something is blocking), colonist count, and game version.test_statusreturns 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_indexinstead 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, andrun_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_TOKENis present and connects only to127.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 explicitconfirm: 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)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi