Skip to main content
Glama

RIMAPI MCP

English | 简体中文

Let an AI client observe and control RimWorld through an existing RIMAPI REST API. This adapter runs locally over stdio, requires Python 3.11 or later, and uses the official Python MCP SDK. The client computer does not need RimWorld or Xvfb installed.

AI client → local stdio MCP → HTTPS / Tailscale / localhost → RimWorld API
Browser   → Cloudflare Access → Tunnel → RimWorld game viewer (optional)

The game computer must already run a compatible RIMAPI service. The adapter can connect to a public HTTPS API, a reachable Tailscale host, or localhost. The game viewer and its authentication are configured separately on the game host.

Install

git clone https://github.com/Zhangkuns/rimapi-mcp.git
cd rimapi-mcp
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
cp .env.example .env
chmod 600 .env

Related MCP server: termcp

Configure your private connection

For an existing HTTPS deployment, edit .env:

RIMAPI_BASE_URL=https://rimapi.example.com/api/v1
RIMAPI_API_TOKEN=replace-with-your-game-token
RIMAPI_VIEW_URL=https://rimworld.example.com/
RIMAPI_TIMEOUT_SECONDS=30

Replace the example hostnames and Token with your own values. RIMAPI_API_TOKEN is the game API's Bearer Token, not a Cloudflare management API Token. Keep real addresses and credentials in the private .env.

Setting

Purpose

RIMAPI_BASE_URL

HTTP(S) API host, optionally ending in /api/v1

RIMAPI_API_TOKEN

Token matching the game or public gateway; sent as Authorization: Bearer …

RIMAPI_VIEW_URL

Optional browser viewing URL; does not affect API requests

RIMAPI_TIMEOUT_SECONDS

Request timeout in seconds; defaults to 30

For a local game, use http://localhost:8765/api/v1. For a Tailscale deployment, use a reachable game hostname and its configured API port, such as http://game-host:18765/api/v1; the client needs tailnet access. A public HTTPS API does not require Tailscale on the client.

The default .env is loaded from beside rimapi_server.py, regardless of the working directory. Use --env-file /absolute/path/to/.env to select another file. Exported environment variables take precedence. Reconnect the MCP service after changing configuration so its process reads the new values.

An empty Token works only when the server permits unauthenticated access. Setting a client Token does not enable authentication on the game server. The adapter does not create a tunnel, DNS records, an Access policy, or a game viewer.

HTTPS and viewer authentication

A deployment can publish two separate hostnames through Cloudflare Tunnel while keeping the API proxy, noVNC, and VNC listeners on loopback:

Entry point

Authentication

Game viewer

Cloudflare Access login, for example an email allowlist with one-time codes; protect the page, assets, and WebSocket handshake

REST API

Bearer Token on every public API request, without an interactive browser login

For that deployment, configure Access and origin validation before publishing the viewer hostname. Enforce Bearer authentication at the public API gateway on all paths, including /version and /capabilities, which the native game server exempts. These are deployment requirements; the adapter does not enforce the gateway's configuration.

Browser login and API authentication are separate. The game Token cannot log in to the viewer; an Access browser session does not authenticate this adapter. Point RIMAPI_BASE_URL at the API hostname, and open RIMAPI_VIEW_URL in your browser to log in to the viewer. The adapter uses rimapi-mcp/1.0 as its User-Agent for API requests.

This repository provides stdio MCP. The client must be able to launch the local Python process. A cloud-only assistant that accepts a remote HTTP MCP URL needs a separately implemented and authenticated HTTP MCP service or a supported local execution bridge. Making the REST API public does not turn it into an HTTP MCP endpoint or automatically connect Dots.

Connect an MCP client

Register a local stdio server using absolute paths to the virtual environment's Python, the script, and the private .env:

{
  "mcpServers": {
    "rimapi": {
      "command": "/absolute/path/to/rimapi-mcp/.venv/bin/python",
      "args": [
        "/absolute/path/to/rimapi-mcp/rimapi_server.py",
        "--env-file",
        "/absolute/path/to/rimapi-mcp/.env"
      ]
    }
  }
}

For a local Codex CLI installation:

codex mcp add rimapi -- \
  /absolute/path/to/rimapi-mcp/.venv/bin/python \
  /absolute/path/to/rimapi-mcp/rimapi_server.py \
  --env-file /absolute/path/to/rimapi-mcp/.env

Check the connection and play

.venv/bin/python rimapi_server.py --check
.venv/bin/python smoke.py

--check reads discovery and protected game state, reporting authentication and credential status without printing the Token. smoke.py checks the official MCP handshake, tool discovery, API/reference lookup, and an actual MCP screenshot. With no map loaded, it reports the screenshot error. The optional --settings-roundtrip flag changes and restores the game's run-in-background setting.

Ask the AI to call rimapi_status and rimapi_gameplay_guide first, confirm the game instance, loaded save, and authentication, then observe, act, and read back the result. The gameplay guide is currently in Chinese.

Tool

Purpose

rimapi_status

Version, DLC, authentication, and protected game state

rimapi_search_endpoints

Search the connected game's current routes and contract metadata

rimapi_search_reference / rimapi_read_reference

Find bundled contracts, examples, controllers, and request DTOs

rimapi_read / rimapi_write

GET and explicit writes, with separate query/body and optional idempotency key

rimapi_screenshot

Return an actual MCP image when a map is loaded

rimapi_gameplay_guide

Read the normal-play instructions

Requests only target the configured game; there is no shell or arbitrary-URL tool. Writes are never automatically retried. A timeout means the outcome is unknown: read current state before retrying. HTTP 200 or a queued operation does not prove a pawn job has finished. Read the reference before selecting parameters; an empty runtime parameters list does not mean an endpoint has no inputs.

API and reference updates

The adapter uses generic read/write tools and discovers routes from the connected game's /capabilities on each endpoint search. New API routes or body fields do not require a separate MCP tool. Native UI controls include /game/preferences, /game/key-bindings, /game/play-settings, /buildings/bill/options, /buildings/bill/configure, and /building/books / /building/books/eject. Search the game-preferences and ui-option-repairs references for their contracts; read current legal choices before writing.

Inside the RIMAPI source tree, reference discovery includes current API documents and controller/DTO files. A standalone package instead reads its bundled references/ snapshot. After API changes, regenerate the package from the updated RIMAPI checkout, synchronize it to client installations, and reconnect MCP to load newly added reference paths. The game must also load the matching DLL: updating MCP or its reference files does not update a running game. Use live endpoint discovery to confirm availability.

Troubleshooting

Symptom

Check

API returns 401

Token matches the game/gateway; .env was reloaded; exported variables are not overriding it

API returns 302 or a login page

API hostname and gateway authentication; the adapter does not complete browser Access login or follow redirects

API returns 403 or Cloudflare 1010

Update the adapter and inspect the relevant Cloudflare security event

Connection fails

Game, API gateway, and tunnel are running; hostname is reachable; Tailscale is connected if using a tailnet address

AI cannot start the MCP service

Client supports local stdio servers and uses valid absolute paths

Privacy, tests, and source

.gitignore excludes .env and its backups, personal mcp-config.json, .venv, and runtime data. The example file contains only generic values. Keep real hostnames, IPs, emails, Tokens, and tunnel credentials out of commits; inspect git status --short before publishing.

The standalone references/ folder contains API documentation and controller/DTO source snapshots for parameter lookup. The client does not execute those sources. Available routes depend on the connected game's version.

.venv/bin/python -m unittest discover -s . -p 'test_*.py' -v

Tests use a local HTTP fixture and do not require a running game. package.py DESTINATION creates a standalone copy with both READMEs and the API references; private configuration and environments are excluded. The adapter comes from the RIMAPI project's mcp/ directory; references originate from AppSprout-dev/RIMAPI and subsequent development. The standalone package retains the GPL terms in LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Windows-local MCP for Steam Balatro: tool-calling AI reads player-visible state, chooses and executes native actions, confirms results, and saves local experience. Glama's Linux sandbox can introspect MCP and run game-independent tools such as calculate, but cannot connect to Balatro on the user's Windows machine. Without the local game, health reports disconnected.
      12
      4
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Gives MCP-compatible AI agents a full local terminal over stdio, enabling shell command execution, file reads and writes, content search, background processes, and stateful tmux sessions with variable capture, auditing, and a configurable command denylist. Requires no deployment or cloud setup.
      15
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to read and write Elgato Stream Deck desktop profile manifests, generate icons, wrap shell commands in script-backed keys, and restart the app so edits take effect. It runs either locally over stdio or remotely over a bearer-token-gated Streamable HTTP transport that adds a health-check tool.
      9
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A stdio or localhost/Tailscale HTTP MCP server that lets outside coding agents list and message your signed-in Desktop bots, read and wait on replies, check status, and reach a Tailscale-connected Linux VM over SSH using scoped, expiring gateway tokens.
      94 npm
      10
      MIT