GMod MCP Tool

MCP (Model Context Protocol) server for Garry's Mod — RCON, Lua execution, window control, screenshots, and SFTP file management.

Features

• RCON — connect to GMod server, execute commands and Lua code
• Screenshots — capture GMod window, zoom into specific areas, read console [Windows]
• Window Control — focus, send keystrokes, console commands [Windows]
• SFTP — read, write, list, delete files on remote server

Quick Start

npx gmod-mcp

MCP Client Configuration

Claude Desktop / Claude Code / Cursor:

{
  "mcpServers": {
    "gmod": {
      "command": "npx",
      "args": ["-y", "gmod-mcp"]
    }
  }
}

With SFTP credentials via environment variables:

{
  "mcpServers": {
    "gmod": {
      "command": "npx",
      "args": ["-y", "gmod-mcp"],
      "env": {
        "SFTP_HOST": "your-server.com",
        "SFTP_PORT": "22",
        "SFTP_USER": "root",
        "SFTP_PASSWORD": "your-password"
      }
    }
  }
}

Tools (15)

RCON (4 tools)

Tool	Description
gmod_connect	Connect to GMod server via RCON
gmod_execute_rcon	Execute RCON command
gmod_execute_lua	Execute Lua code (auto-splits by statements)
gmod_disconnect	Disconnect from server

gmod_connect

Parameter	Required	Description
host	Yes	Server IP or hostname
port	No	RCON port (default: 27015)
password	Yes	RCON password

gmod_execute_rcon

Parameter	Required	Description
command	Yes	RCON command (status, say Hello!, kick Player)

Blocked commands: quit, exit, rcon_password, _restart

gmod_execute_lua

Parameter	Required	Description
code	Yes	Lua code to execute

Multi-statement code is automatically split by ; into separate lua_run calls. Local variables are converted to _G.__mcp_ globals for cross-statement persistence.

_G.plys = player.GetAll(); print(#_G.plys .. " players online")

---

Screenshots (3 tools) [Windows only]

Tool	Description
gmod_screenshot	Full window screenshot (PNG)
gmod_zoom	Crop + zoom specific area
gmod_read_console	Screenshot of game console

gmod_zoom

Parameter	Required	Description
x	Yes	X offset (% if 0-100, px if >100)
y	Yes	Y offset
width	Yes	Crop width
height	Yes	Crop height

---

Window Control (3 tools) [Windows only]

Tool	Description
gmod_focus_window	Bring GMod window to foreground
gmod_send_keys	Send keystrokes to GMod
gmod_console_command	Type command in game console [Experimental]

gmod_send_keys

Parameter	Required	Description
keys	Yes	SendKeys format string

SendKeys format: {ENTER}, {ESCAPE}, {TAB}, {F1}-{F12}, + (Shift), ^ (Ctrl), % (Alt)

gmod_console_command

Parameter	Required	Description
command	Yes	Console command (e.g. connect 1.2.3.4:27015)

Experimental: may not work correctly with non-English keyboard layouts.

---

SFTP (5 tools)

Tool	Description
sftp_connect	Connect to SFTP server
sftp_read_file	Read remote file
sftp_write_file	Write/upload file
sftp_list_dir	List directory contents
sftp_delete	Delete remote file
sftp_disconnect	Disconnect from SFTP

sftp_connect

Parameter	Required	Description
host	Yes	Server hostname (or SFTP_HOST env)
port	No	SSH port, default 22 (or SFTP_PORT env)
username	Yes	SSH username (or SFTP_USER env)
password	No	SSH password (or SFTP_PASSWORD env)
privateKey	No	SSH private key content

Requirements

• Node.js >= 18
• GMod server with RCON enabled (rcon_password in server.cfg)
• Windows for screenshot and window control tools
• SSH access for SFTP tools

Security

• Destructive RCON commands (quit, exit, rcon_password) are blocked
• Dangerous Lua functions (file.Delete, RunConsoleCommand, CompileString) trigger warnings
• RCON password is cleared from memory after authentication
• SFTP credentials can be passed via environment variables (no hardcoding)

Troubleshooting

Connection failed — check server is running, RCON password is correct, port is not firewalled

Lua code fails — multi-line code must use ; separators. local variables don't persist between lua_run calls (auto-converted to _G.__mcp_*)

Screenshot returns error — GMod must be running and visible (not minimized). Process name must be hl2.exe or gmod.exe

Console command types wrong characters — switch to English keyboard layout before using gmod_console_command

License

MIT