txadmin-mcp

An MCP server that lets an AI assistant read and administer a FiveM / RedM game server through txAdmin.

Ask "why is the server crashing?", "who's online?", "who banned Dave and why?" or "restart the chat resource" and get a real answer from the live server.

Works against any unmodified txAdmin install. No server-side resource, no config edits, no FXServer restart — it authenticates as an ordinary admin account, exactly like the web panel does.

npx -y txadmin-mcp

Install

Claude Code

claude mcp add txadmin -- npx -y txadmin-mcp \
  -e TXADMIN_URL=http://127.0.0.1:40120 \
  -e TXADMIN_USER=mcp-bot \
  -e TXADMIN_PASS=your-password

Any MCP client (claude_desktop_config.json, .mcp.json, Cursor, …)

{
  "mcpServers": {
    "txadmin": {
      "command": "npx",
      "args": ["-y", "txadmin-mcp"],
      "env": {
        "TXADMIN_URL": "http://127.0.0.1:40120",
        "TXADMIN_USER": "mcp-bot",
        "TXADMIN_PASS": "your-password",
        "TXADMIN_MODE": "write"
      }
    }
  }
}

If your panel is not on the same machine, use its public URL. txAdmin listens on port 40120 by default.

Related MCP server: FiveM Documentation MCP Server

Security

Read this before you configure it — it changes what you should set.

Create a dedicated txAdmin admin account for the MCP. In txAdmin: Admin Manager → Add Admin, then grant only the permissions you want an AI to have. This is the gate that actually matters: txAdmin enforces permissions server-side, so an account without players.ban cannot ban anyone no matter what the model is told to do, including by a malicious player.

TXADMIN_MODE is a second belt, not the boundary. It defaults to write, which excludes every destructive tool. Destructive tools (ban, kick, server stop, arbitrary console) require TXADMIN_MODE=admin and an account holding the permission.

Tools are gated at registration. On startup the server reads its own permissions from txAdmin and only registers tools that pass both gates. The model never sees a tool it cannot use, so it can't waste turns on one or try to work around it.

Console and chat are player-authored. Anything a player can type — chat messages, names, ban reasons — can contain text designed to read as instructions to an AI. All such content is returned inside an explicit untrusted-data block. That is mitigation, not a guarantee, which is the other reason destructive tools are opt-in.

A locked-down account still gets almost everything. Most read routes need no special permission, so a minimal account loses only the console and server-log tools. There is no pressure to over-grant.

Configuration

Modes

Tools

Read — always available

Write — default tier

Admin — requires TXADMIN_MODE=admin

How it works

txAdmin has no official REST API — the only token-authenticated endpoint is /host/status, which exists for hosting providers and returns status only. So this speaks the panel's own web API, the same one the React frontend uses:

1. POST /auth/password with your credentials returns a session cookie and a CSRF token.

2. Every subsequent call sends that cookie plus an x-txadmin-csrftoken header.

3. The live console and playerlist are socket.io rooms, joined via the handshake query string.

Sessions are cached at ~/.cache/txadmin-mcp (mode 0600, honouring XDG_CACHE_HOME). This is not an optimisation: txAdmin rate-limits logins to 10 attempts per 15 minutes per IP, and an MCP server is spawned fresh for every assistant session. Without the cache you would lock yourself out of your own panel within a day. Your password is never written to disk.

Because this consumes an unofficial API, all route knowledge lives in two files (src/txadmin/client.ts and src/txadmin/socket.ts). A txAdmin update touches those and nothing else.

Compatibility

Developed against txAdmin master as of July 2026 and verified against a live txAdmin v8.0.1 panel. Requires Node 20 or newer; tested on Node 20, 22 and 24.

If a txAdmin update breaks something, txadmin_whoami is the fastest check — it exercises authentication, CSRF and permission reading in one call. Please open an issue with what it prints.

Troubleshooting

Development

npm install
npm test        # 103 tests, no FiveM server required
npm run build

Tests run against a mock txAdmin that reproduces the real authentication handshake — including rejecting requests without a CSRF header and silently declining socket rooms the account lacks permission for, which is how the real server behaves.

To verify against a live panel (read-only, safe on production):

TXADMIN_URL=http://127.0.0.1:40120 TXADMIN_USER=x TXADMIN_PASS=y npm run smoke

Releasing

Releases publish from CI via npm trusted publishing (OIDC) — no npm token is stored in this repository.

npm version patch && git push --follow-tags

The tag triggers .github/workflows/release.yml, which builds, runs the full suite, and publishes.

License

MIT