screeps-mcp

A stdio Model Context Protocol server that lets Claude Code (and any other MCP client) inspect and control your Screeps: World colony. Read rooms, push code, tail the console, read/write Memory — all from Claude, with a human-in-the-loop gate on anything that touches your live active branch.

What you get

22 tools across six categories:

| Category | Tools | |---|---| | Profiles | list_profiles, get_active_profile | | World | whoami, get_room_objects, get_room_terrain, get_room_status, get_shard_info, get_gcl_gpl, get_cpu | | Map | get_map_stats, get_room_overview, get_encoded_room_image | | Code | list_branches, get_code, push_code, set_active_branch, clone_branch | | Console | execute_console, get_console_output, clear_console_buffer | | Memory | get_memory, set_memory |

Scope is deliberately bounded: no market, no memory segments, nothing that spends credits.

Requirements

• Node.js >= 20
• A Screeps account (official MMO or a private server)
• Claude Code (or any MCP client that supports elicitation)

Quick start

Grab a token at https://screeps.com/a/#!/account/auth-tokens (grant Full access).

Option A — config file (recommended)

npx screeps-mcp init          # creates ~/.screeps-mcp/config.json

The init command asks for your token, verifies it against screeps.com, and writes the config for you (mode 0600).

Then register the server with Claude Code:

claude mcp add screeps -- npx -y screeps-mcp

Option B — environment variable (no config file)

Pass your token directly through Claude Code's MCP environment. Add this to your .claude.json (project or user scope) under mcpServers:

{
  "screeps": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "screeps-mcp@latest"],
    "env": {
      "SCREEPS_MMO_TOKEN": "your-token-here"
    }
  }
}

The server reads ~/.screeps-mcp/config.json which supports ${ENV_VAR} interpolation, so the token is resolved at startup.

Verify

Restart Claude Code (or run /reload-plugins). In a new chat, ask "who am I on Screeps?" — if it prints your username, you're connected.

Building from source

git clone https://github.com/Khochawongwat/screeps-mcp.git
cd screeps-mcp
npm install && npm run build
node dist/index.js init
claude mcp add screeps -- node dist/index.js

Manual / advanced configuration

If you'd rather write ~/.screeps-mcp/config.json by hand — to use a private server, define multiple profiles, or keep tokens in env vars — the schema is:

{
  "defaultProfile": "mmo",
  "profiles": {
    "mmo": {
      "host": "screeps.com",
      "secure": true,
      "token": "${SCREEPS_MMO_TOKEN}",
      "shardDefault": "shard3"
    },
    "local": {
      "host": "127.0.0.1",
      "port": 21025,
      "secure": false,
      "username": "your-username",
      "password": "${SCREEPS_LOCAL_PASSWORD}"
    }
  }
}

Rules:

• A profile uses either token or username + password — not both.
• defaultProfile must match an existing profile key.
• ${ENV_VAR} interpolation is applied when the config is loaded, so secrets can stay out of the file.
• Full sample at .screeps-mcp.example.json.

The active-branch safety gate

This is the one thing you need to understand about writes.

Any tool that could overwrite your live running code or live Memory — push_code, set_active_branch, clone_branch (when the destination is active), set_memory — pauses and asks you to confirm in the Claude UI before making the call. This uses the MCP elicitation feature: Claude cannot bypass it, and if your MCP client does not support elicitation the tool returns an error telling you to push manually.

You will see a prompt like:

push_code wants to overwrite branch default (your active branch) on profile mmo. Approve?

Read-only operations (get_code, get_room_*, whoami, etc.) never trigger the gate.

Console output model

Screeps streams console logs continuously over a WebSocket. screeps-mcp keeps a persistent subscription per profile and writes every line into an in-memory ring buffer. Tools work against the buffer, not the live socket:

• execute_console — run a command; output lands in the buffer
• get_console_output — read the buffer (optionally filtered by a since-tick)
• clear_console_buffer — drop everything currently buffered

The buffer survives across tool calls within the same Claude Code session. It is cleared when the MCP server process restarts.

Troubleshooting

| Symptom | Likely cause | |---|---| | Tool 'push_code' failed: client does not support elicitation | Your MCP client is too old or has elicitation disabled. Update Claude Code, or push manually. | | defaultProfile must reference an existing profile | Typo in defaultProfile — it must match a key under profiles. | | init: Verification failed: 401 | Token is wrong, expired, or missing scopes. Regenerate it and rerun init. | | ECONNREFUSED 127.0.0.1:21025 | Your private server isn't running, or the port is wrong. | | Tools don't appear in Claude | For a source install, forgot to npm run build or registered a relative path. Use the absolute path to dist/index.js. | | Failed to connect with no error | If using env-var interpolation (${SCREEPS_MMO_TOKEN}), ensure the variable is set in the MCP server's env block in .claude.json — Claude Code does not inherit your shell environment. | | Config not picked up | Must live at ~/.screeps-mcp/config.json. On Windows: C:\Users\<you>\.screeps-mcp\config.json. |

Check what Claude Code sees:

claude mcp list

Uninstall

claude mcp remove screeps
rm -rf ~/.screeps-mcp

Development

Tests use vitest + nock; no real network calls.

npm run lint && npm run typecheck && npm test && npm run build

Run a single test file:

npx vitest run tests/unit/codeWriteTools.test.ts

Contributions welcome — please open an issue before starting non-trivial work.

License

Apache-2.0 — see LICENSE.