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