Skip to content
Back to search

gmod-mcplink

MCP server for Garry's Mod that reaches the game through a native socket module instead of file polling

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/riggs9162--gmod-mcplink/badge.svg)](/listings/riggs9162--gmod-mcplink)

HTML

<a href="/listings/riggs9162--gmod-mcplink"><img src="/api/listings/riggs9162--gmod-mcplink/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You need Node.js 20 or newer for the server.

1. **Module.** Download the DLLs for your platform from the newest entry on the [releases page](../../releases) and put them in `garrysmod/lua/bin/` (create the folder if it does not exist). `gmsv_` files serve the server realm and `gmcl_` files the client realm; the suffix must match the game build:

| Game build | Files | | --- | --- | | Windows, 64-bit branch | `gmsv_mcplink_win64.dll`, `gmcl_mcplink_win64.dll` | | Windows, default 32-bit | `gmsv_mcplink_win32.dll`, `gmcl_mcplink_win32.dll` | | Linux, 64-bit branch | `gmsv_mcplink_linux64.dll`, `gmcl_mcplink_linux64.dll` | | Linux, default 32-bit | `gmsv_mcplink_linux.dll`, `gmcl_mcplink_linux.dll` |

2. **Addon.** Copy the contents of `addon/` (or unpack `mcplink-addon.zip` from the release) into `garrysmod/addons/mcplink/`.

3. **Server.** Build it once:

   cd server
   npm install
   npm run build

4. **Register it with your agent.** For Claude Code:

   claude mcp add gmod --scope user --env GMOD_DIR="<path to>/garrysmod" -- node "<path to>/gmod-mcplink/server/dist/index.js"

Any other MCP client works the same way: the command is `node`, the single argument is the path to `server/dist/index.js`, and `GMOD_DIR` goes in the server's environment.

5. Add `-condebug` to the game's launch options if you want `gmod_log` to work, then start the game.

On Windows, `tools/install.ps1 -GameDir "<path to>/garrysmod"` does steps 1 to 3 from source. It needs Rust.

Configuration

| Variable | Meaning | | --- | --- | | `GMOD_DIR` | The `garrysmod` directory. Defaults to the standard Steam location on Windows. | | `GMOD_SERVER_DIR` | Overrides `GMOD_DIR` for the server realm, for a dedicated server installed elsewhere. | | `GMOD_CLIENT_DIR` | Overrides `GMOD_DIR` for the client realm. |

A listen server or single-player game needs only `GMOD_DIR`. To drive a dedicated server and a separate game client at once, point `GMOD_SERVER_DIR` and `GMOD_CLIENT_DIR` at their two directories.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 142 lines
  1. # gmod-mcplink
  2. An [MCP](https://modelcontextprotocol.io) server for Garry's Mod that reaches the game through a small native module instead of polling files. An AI agent can run Lua, send console commands, read the console log and take screenshots in a running game, on the server realm and the client realm, with answers arriving within a frame.
  3. ## How it fits together
  4. ```
  5. agent <-- MCP over stdio --> server/ (Node) <-- loopback TCP --> gmsv_/gmcl_mcplink DLL <--> addon/ (GLua)
  6. ```
  7. | Part | Job |
  8. | --- | --- |
  9. | `module/` | Rust binary module. Opens a listener on `127.0.0.1`, checks a session token and hands request lines to Lua. It knows nothing about MCP or about what a request means. |
  10. | `addon/` | GLua bridge. Polls the module every frame, runs the handler for each request and sends the answer back. All tool behaviour lives here, so it changes without recompiling anything. |
  11. | `server/` | Node MCP server. Speaks MCP to the agent and newline-delimited JSON to the module. |
  12. GLua has no sockets and cannot accept connections, and the game blocks HTTP requests to local addresses for clients. A pure Lua bridge is therefore left with polling files in `data/`. The module removes that limit and nothing else: it is a transport, deliberately kept thin.
  13. ## Status
  14. Version 0.1.00, pre-production. The module, the bridge and the server have been run together end to end against the game's own LuaJIT runtime (`lua_shared.dll`, 64-bit Windows) outside the game. They have **not** yet been exercised inside a live game session, and the Linux builds are compiled by CI but untested. Expect rough edges and report what you find.
  15. ## Install
  16. You need Node.js 20 or newer for the server.
  17. 1. **Module.** Download the DLLs for your platform from the newest entry on the [releases page](../../releases) and put them in `garrysmod/lua/bin/` (create the folder if it does not exist). `gmsv_` files serve the server realm and `gmcl_` files the client realm; the suffix must match the game build:
  18. | Game build | Files |
  19. | --- | --- |
  20. | Windows, 64-bit branch | `gmsv_mcplink_win64.dll`, `gmcl_mcplink_win64.dll` |
  21. | Windows, default 32-bit | `gmsv_mcplink_win32.dll`, `gmcl_mcplink_win32.dll` |
  22. | Linux, 64-bit branch | `gmsv_mcplink_linux64.dll`, `gmcl_mcplink_linux64.dll` |
  23. | Linux, default 32-bit | `gmsv_mcplink_linux.dll`, `gmcl_mcplink_linux.dll` |
  24. 2. **Addon.** Copy the contents of `addon/` (or unpack `mcplink-addon.zip` from the release) into `garrysmod/addons/mcplink/`.
  25. 3. **Server.** Build it once:
  26. ```
  27. cd server
  28. npm install
  29. npm run build
  30. ```
  31. 4. **Register it with your agent.** For Claude Code:
  32. ```
  33. claude mcp add gmod --scope user --env GMOD_DIR="<path to>/garrysmod" -- node "<path to>/gmod-mcplink/server/dist/index.js"
  34. ```
  35. Any other MCP client works the same way: the command is `node`, the single argument is the path to `server/dist/index.js`, and `GMOD_DIR` goes in the server's environment.
  36. 5. Add `-condebug` to the game's launch options if you want `gmod_log` to work, then start the game.
  37. On Windows, `tools/install.ps1 -GameDir "<path to>/garrysmod"` does steps 1 to 3 from source. It needs Rust.
  38. ### Configuration
  39. | Variable | Meaning |
  40. | --- | --- |
  41. | `GMOD_DIR` | The `garrysmod` directory. Defaults to the standard Steam location on Windows. |
  42. | `GMOD_SERVER_DIR` | Overrides `GMOD_DIR` for the server realm, for a dedicated server installed elsewhere. |
  43. | `GMOD_CLIENT_DIR` | Overrides `GMOD_DIR` for the client realm. |
  44. A listen server or single-player game needs only `GMOD_DIR`. To drive a dedicated server and a separate game client at once, point `GMOD_SERVER_DIR` and `GMOD_CLIENT_DIR` at their two directories.
  45. ## Tools
  46. | Tool | What it does |
  47. | --- | --- |
  48. | `gmod_status` | Reports which realms are reachable, the map, gamemode, players and available operations. |
  49. | `gmod_lua` | Runs a Lua chunk and returns its return values, everything it printed, and the error with a traceback if it failed. A bare expression needs no `return`. |
  50. | `gmod_cmd` | Runs a console command in the server console or as the local player. |
  51. | `gmod_log` | Returns the tail of `console.log`, optionally filtered by a regular expression. |
  52. | `gmod_screenshot` | Captures the next frame the local player sees and returns it as an image. |
  53. | `gmod_call` | Calls an operation your own addon or gamemode registered. |
  54. `gmod_lua`, `gmod_cmd`, `gmod_log` and `gmod_call` take a `realm` of `server` (the default) or `client`.
  55. ## Adding your own operations
  56. Any addon or gamemode can expose a purpose-built operation, which is safer and cheaper for an agent than composing raw Lua each time:
  57. ```lua
  58. hook.Add("InitPostEntity", "myAddon.RegisterMcpOperations", function()
  59. if ( !mcpBridge ) then
  60. return
  61. end
  62. mcpBridge.RegisterHandler("inventory", function(request)
  63. local client = Player(request.userID)
  64. if ( !IsValid(client) ) then
  65. return {ok = false, error = "No such player."}
  66. end
  67. return {ok = true, items = myAddon.GetItemNames(client)}
  68. end)
  69. end)
  70. ```
  71. The agent calls it with `gmod_call`, passing `operation = "inventory"` and `arguments = {userID = 2}`. A handler either returns its response table, or returns nothing and calls the `reply` function it receives as its second argument later, which is how `screenshot` waits for the next frame.
  72. ## Security
  73. This is a development tool. It runs arbitrary Lua and console commands on request, so treat the module like an open RCON port and install it only where that is acceptable.
  74. - The listener binds to `127.0.0.1` on a random free port and is never reachable from another machine.
  75. - Each game start generates a fresh 192-bit token. A connection must present it first, and is dropped without a reply if it is wrong or late.
  76. - The port and token are written to `garrysmod/data/mcplink/<realm>.json`. Anything that can read that file can control the game, which already holds for any process running as your user.
  77. - The addon does nothing on a machine that lacks the module, so players who receive the client files from your server are unaffected.
  78. - Do not install the module on a public production server.
  79. ## Limits
  80. - Requests are handled in the `Think` hook. A dedicated server with no players hibernates and stops thinking, so the bridge sets `sv_hibernate_think 1` when it starts.
  81. - A paused single-player game does not think either; requests wait until it resumes.
  82. - The token and port change on every map change. The server reconnects on the next request by itself.
  83. - `gmod_cmd` cannot return a command's console output; read it with `gmod_log`.
  84. - `render.Capture` is refused by the game while the main menu is open, so `gmod_screenshot` fails there.
  85. - The menu realm is not supported.
  86. ## Protocol
  87. For anyone writing another client. Every message is one line of UTF-8 JSON ending in `\n`.
  88. 1. Read `data/mcplink/<realm>.json` and connect to `127.0.0.1` on its `port`.
  89. 2. Send the `token` as the first line. The module answers `{"hello":"mcplink","version":"..."}` or closes the connection.
  90. 3. Send requests as `{"id": 1, "op": "lua", "code": "..."}`. Built-in operations are `status`, `lua` (`code`), `cmd` (`command`) and, on the client, `screenshot` (`quality`).
  91. 4. Each answer carries the same `id` and an `ok` flag, plus `error` when `ok` is false. Answers may arrive out of order.
  92. ## Building from source
  93. ```
  94. cargo build --release --manifest-path module/Cargo.toml
  95. ```
  96. The result is `module/target/release/mcplink.dll` on Windows or `libmcplink.so` on Linux. Copy it to `garrysmod/lua/bin/` twice, as `gmsv_mcplink_<suffix>.dll` and `gmcl_mcplink_<suffix>.dll`; the two are the same file. Add `--target i686-pc-windows-msvc` or `--target i686-unknown-linux-gnu` for the 32-bit game.
  97. ## License
  98. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.