SourceMod MCP Server

A Model Context Protocol server that gives Claude general-purpose, programmatic control over a local TF2 / SourceMod game server: query live state, run commands, compile and hot-load plugins, stream telemetry, debug runtime errors, and write throwaway one-off scripts — all through the full SourceMod native API rather than by scraping console text.

Architecture

Two processes on the same machine, connected by a persistent local TCP socket:

┌─────────────┐   stdio    ┌──────────────────┐   local TCP    ┌──────────────────────┐
│   Claude    │◄──────────►│   MCP server     │◄──────────────►│   Bridge plugin      │
│  (client)   │   (MCP)    │  (TypeScript)    │  JSON frames   │  (SourcePawn, in     │
└─────────────┘            │                  │                │   the gameserver)    │
                           │ • tool surface   │                │ • intent dispatch    │
                           │ • spcomp / files │                │ • event push         │
                           │ • RCON fallback  │                │ • full SM native API │
                           └──────────────────┘                └──────────────────────┘

• MCP server (src/, Node + TypeScript, ESM): exposes the tools to Claude over stdio, runs the local socket server the plugin connects to, invokes spcomp, edits files under whitelisted roots, and falls back to RCON when the bridge is down.

• Bridge plugin (plugin/, SourcePawn + sm-ext-socket + sm-ripext): runs inside the gameserver, receives JSON intents, executes them with the full SourceMod API, and pushes game events back.

The MCP server is the TCP server; the plugin is the client and reconnects every 5 s if the link drops. stdout is owned by the MCP transport — all server diagnostics go to stderr.

Related MCP server: Minecraft RCON MCP Server

Wire protocol

Raw local TCP carrying length-prefixed JSON frames:

┌────────────────────────┬─────────────────────────────────┐
│ 4-byte length (BE u32) │  UTF-8 JSON payload (that many) │
└────────────────────────┴─────────────────────────────────┘

• Length prefix is a big-endian unsigned 32-bit byte count of the JSON that follows.

• Max frame size is 8 MiB (MAX_FRAME_BYTES); larger frames are a protocol error.

• Frames may be split across TCP reads or coalesced; both sides decode incrementally.

Message shape

{
  "id":      "uuid-or-correlation-id",   // correlates an intent with its result
  "type":    "intent" | "result" | "event",
  "action":  "console",                   // the verb; "" on results
  "payload": { /* action-specific */ }
}

• intent — MCP → plugin. A request to do something. The plugin replies with a result carrying the same id.

• result — plugin → MCP. payload is { ok: boolean, data?: unknown, error?: string }.

• event — plugin → MCP, unsolicited. Telemetry (connects, deaths, chat, round/map changes) and structured errors (action: "sm_error"). No reply.

Intents are correlated by id: the MCP server keeps a pending-intent registry and resolves the matching promise when the result arrives (or rejects on timeout).

MCP tools

30 tools, grouped by concern.

Control

Telemetry

Build & deploy

Files

Config (.cfg)

Debugging

Scratch scripting (ephemeral, zero-trace)

Zero-trace guarantee: the scratch dir is wiped on startup (the real backstop against crash orphans) and on shutdown; kills remove every file from both scratch and plugins dirs; failed compiles leave nothing on disk. Promotion to a real plugin is the only way scratch content persists, and it is always explicit.

Bridge plugin actions

Actions the plugin's dispatcher (MCP_HandleAction) understands, invoked via send_intent or a typed tool:

Events pushed by the plugin include player_connect, player_disconnect, player_death, player_say, round_start, round_end, map_start, and sm_error (structured runtime errors).

Safety

MCP has no interactive mid-call prompt, so destructive actions use a two-step confirmation gate:

1. A destructive console/RCON command called without confirm: true returns a preview ({ requiresConfirmation: true, reason, hint }) and does not run.

2. Re-issue the same tool with confirm: true to execute.

Commands classified as destructive (in src/safety.ts): quit/exit/restart, map/changelevel, kickall, kick/ban/addip, exec, mp_restartgame/mp_restartround, and anything that rewrites server auth (rcon_password/sv_password). Read-only and benign commands run straight through. This applies to both rcon_exec and the console action of send_intent.

Additional safety layers: all filesystem tools are confined to whitelisted roots via a resolve-and-confine path guard (blocks ../ traversal); the RCON password lives only in the environment, never in code; and all inputs are validated with zod schemas at the tool boundary.

Setup

Prerequisites

• Node.js ≥ 20 (developed on v24), npm.

• A TF2 / SourceMod server you control locally.

• spcomp (bundled with SourceMod) for compiling plugins.

• The sm-ext-socket extension and sm-ripext installed in the gameserver.

1. Install and build the MCP server

npm install
npm run build

2. Configure

Copy config.example.json to config.json and fill in the paths and credentials:

The config file is resolved in order: an explicit path passed as the first CLI argument (node dist/index.js C:/path/config.json), then the SM_MCP_CONFIG env var, then config.json next to the project root. Any field may be omitted; documented defaults apply.

3. Compile and load the bridge plugin

Compile plugin/scripting/mcp_bridge.sp with spcomp (its includes are under plugin/scripting/include/mcp_bridge/), deploy the .smx into the gameserver's plugins dir, and load it. The plugin connects to the MCP socket on load and reconnects automatically. Its host/port are set via the mcp_bridge_host / mcp_bridge_port ConVars; check the link with the mcp_bridge_status admin command.

4. Register the MCP server with Claude

Point your MCP client at the built server (stdio transport):

{
  "mcpServers": {
    "sourcemod": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/sourcemod-mcp"
    }
  }
}

Or register it from the CLI:

claude mcp add sourcemod --scope user -- node /path/to/sourcemod-mcp/dist/index.js

Development

npm run typecheck   # tsc --noEmit
npm run build       # compile to dist/
npm run dev         # watch mode
npm start           # run the built server

Project layout

src/
  index.ts            entry point: boots socket + tools, wires shutdown
  config.ts           env → typed config
  protocol.ts         frame encode/decode, message types
  socket-server.ts    the local TCP server + pending-intent registry
  safety.ts           destructive-command classifier + confirmation gate
  compiler.ts         spcomp invocation + diagnostic parsing
  rcon.ts             RCON fallback
  path-guard.ts       resolve-and-confine within whitelisted roots
  scratch-manager.ts  ephemeral scratch lifecycle + zero-trace cleanup
  event-buffer.ts     live in-memory event ring buffer
  debug-store.ts      error ring buffer + on-disk event log
  logger.ts           stderr structured logging
  tools/              the MCP tool modules (one per concern)
plugin/
  scripting/mcp_bridge.sp                main bridge plugin
  scripting/include/mcp_bridge/*.inc     protocol, dispatch, telemetry, debug