☢️ stalker-mcp

Let an AI assistant see, query and drive a live game of S.T.A.L.K.E.R. Anomaly.

An MCP server that connects Claude (or any MCP client) to S.T.A.L.K.E.R. Anomaly running under Mod Organizer 2: run Lua inside the game, spawn items, read logs and crashes, take screenshots, resolve mod conflicts.

What is this?

Modding Anomaly usually means: edit a script → restart the game → wait two minutes → read a 50 000-line log. stalker-mcp gives an AI assistant direct access to the running game, so you can just ask:

"Why did the game crash?" · "Which mod overrides xr_effects.script?" · "Spawn 5 medkits and a Vintorez." · "Set midnight and a storm, then take a screenshot." · "How many stalkers are alive on this level, grouped by faction?"

The assistant answers by calling tools: it runs Lua in the game's own environment (db.actor, alife(), level, ini_sys, every xr_* module), reads the engine log, walks your MO2 load order and looks at the screen.

Related MCP server: ue-bridge

How it works

flowchart LR
    C["🤖 AI client<br/>Claude Code · Claude Desktop · …"]
    S["🐍 server.py<br/>MCP server (stdio)"]
    B[("📁 bridge folder<br/>req.lua · resp.json · heartbeat.json")]
    G["☢️ Anomaly<br/>+ MCP-Bridge mod"]
    M["🗂️ MO2<br/>mods · profiles · logs"]

    C <-- MCP --> S
    S -- "Lua request" --> B
    B -- "polled every 100 ms" --> G
    G -- "JSON answer + heartbeat" --> B
    B --> S
    S -- "reads / edits" --> M

• The game side is a tiny Lua mod, MCP-Bridge (mcp_bridge.script). Every 100 ms it checks req.lua, runs the code with xpcall and writes the result to resp.json. Once a second it writes heartbeat.json, so the server knows the game is alive.

• No DLLs, no engine patches, no network ports: plain files only.

• Tools that don't need the game (logs, mods, file search) work even when it is closed.

Tools

game_lua returns game objects as {id, name, section} and vectors as {x, y, z}. Globals you define persist between calls, and print() output is collected.

Requirements

• Windows 10/11

• S.T.A.L.K.E.R. Anomaly 1.5.x (also works with modpacks built on it, e.g. GAMMA)

• A portable Mod Organizer 2 instance

• Python 3.10+

• An MCP client that can run local (stdio) servers: Claude Code, Claude Desktop, Codex CLI, Gemini CLI, Kimi CLI, Cursor, VS Code, Cline, LM Studio… (see Compatibility)

Installation

1. Get the server

git clone https://github.com/DrakuXYZ/stalker-mcp.git
cd stalker-mcp
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt

2. Install the game mod

Close MO2 and the game, then run:

$env:STALKER_GAME = "D:\Games\Anomaly"       # folder with bin\ and gamedata\
$env:STALKER_MO2  = "D:\Games\Anomaly\MO2"   # folder with ModOrganizer.exe
.venv\Scripts\python server.py install

This writes mods\MCP-Bridge with the bridge path filled in and enables it in the active profile.

3. Connect your MCP client

Every client needs the same three things: the command (.venv\Scripts\python.exe), the argument (server.py) and the two environment variables. Pick yours:

Run in cmd or Git Bash (Windows PowerShell 5.1 swallows the --):

claude mcp add stalker -s user -e STALKER_GAME=D:\Games\Anomaly -e STALKER_MO2=D:\Games\Anomaly\MO2 -- D:\stalker-mcp\.venv\Scripts\python.exe D:\stalker-mcp\server.py

All of them use the same mcpServers JSON. Put it into the client's MCP config file:

{
  "mcpServers": {
    "stalker": {
      "command": "D:\\stalker-mcp\\.venv\\Scripts\\python.exe",
      "args": ["D:\\stalker-mcp\\server.py"],
      "env": {
        "STALKER_GAME": "D:\\Games\\Anomaly",
        "STALKER_MO2": "D:\\Games\\Anomaly\\MO2"
      }
    }
  }
}

%USERPROFILE%\.codex\config.toml:

[mcp_servers.stalker]
command = 'D:\stalker-mcp\.venv\Scripts\python.exe'
args = ['D:\stalker-mcp\server.py']

[mcp_servers.stalker.env]
STALKER_GAME = 'D:\Games\Anomaly'
STALKER_MO2 = 'D:\Games\Anomaly\MO2'

.vscode\mcp.json in your workspace (note servers, not mcpServers):

{
  "servers": {
    "stalker": {
      "type": "stdio",
      "command": "D:\\stalker-mcp\\.venv\\Scripts\\python.exe",
      "args": ["D:\\stalker-mcp\\server.py"],
      "env": {
        "STALKER_GAME": "D:\\Games\\Anomaly",
        "STALKER_MO2": "D:\\Games\\Anomaly\\MO2"
      }
    }
  }
}

4. Play. Start the game from MO2 (or ask the assistant to run game_launch), load a save, and ask away. Check the connection with game_status: the bridge should be онлайн (online).

Configuration

Good to know

• The bridge starts with the first loaded save. In the main menu before that, game tools report that the game is not responding. After the first load it also works in the ESC menu and on the death screen.

• The game pauses when it loses focus. Nothing is polled while it is paused. Run the game windowed or borderless with g_always_active on in the console. A custom engine can call _G.on_paused_tick() while paused to keep the bridge alive.

• The bridge folder must be outside the game folder. MO2's virtual file system redirects new files created inside it to overwrite, and the server would never see them. For the same reason req.lua and resp.json are created before the game starts and are only overwritten, never deleted.

• Updated the bridge script? Restart the game. The server checks the bridge version in the heartbeat and refuses to talk to an outdated one.

• mo2_set_mod needs MO2 closed. MO2 rewrites modlist.txt on exit.

• Strings come from the engine in cp1251. The server decodes them, and Cyrillic in requests is sent as cp1251, so it matches the game's own strings.

• Tool descriptions and messages are in Russian. Large models handle that fine.

Compatibility

stalker-mcp is a standard MCP server, so it is not tied to Claude. Any client that runs local (stdio) MCP servers works, with any model inside: Claude, GPT, Kimi, Gemini, Qwen, a local LLM.

⚠️ Security

game_lua runs arbitrary code inside the game. Anomaly's Lua has the io and os libraries, so that code can do anything your Windows user can do.

• Anyone who can write to the bridge folder can run code in your game. The default folder is in your user profile.

• Use it with assistants and prompts you trust.

• Disable the MCP-Bridge mod in MO2 when you don't need it.

Troubleshooting

Disclaimer

stalker-mcp is provided as is, without any warranty. You use it at your own risk. The author is not responsible for anything that happens to your game, saves, mods, modpack, files or computer, including actions taken by an AI assistant through these tools. If you build a modpack or a tool on top of it, that project and its consequences are yours.

License

CC BY-NC-ND 4.0 © 2026 DrakuXYZ

S.T.A.L.K.E.R. is a trademark of GSC Game World. This is an unofficial fan tool.