Package Exports

gmod-mcp
gmod-mcp/src/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (gmod-mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

gmod-mcp