# GMod MCP Tool

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

[![npm](https://img.shields.io/npm/v/gmod-mcp)](https://www.npmjs.com/package/gmod-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 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

```bash
npx gmod-mcp
```

### MCP Client Configuration

**Claude Desktop / Claude Code / Cursor:**

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

**With SFTP credentials via environment variables:**

```json
{
  "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.

```lua
_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