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.

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

| Variable | Required | Default | Description | |---|---|---|---| | TXADMIN_URL | yes | — | Panel base URL, e.g. http://127.0.0.1:40120 | | TXADMIN_USER | yes | — | txAdmin admin username | | TXADMIN_PASS | yes | — | That account's password | | TXADMIN_MODE | no | write | read, write or admin. Cumulative | | TXADMIN_TIMEOUT_MS | no | 15000 | Per-request timeout | | TXADMIN_INSECURE_TLS | no | false | Skip TLS verification. Last resort for a self-signed panel — adding the CA to your trust store is the correct fix |

Modes

| Mode | Exposes | Use when | |---|---|---| | read | 9 read tools | You want observability only, or you're trying it out | | write | + 3 safe write tools | Day-to-day: announcements, warnings, resource reloads | | admin | + 4 destructive tools | You explicitly want bans, kicks, restarts and console access |

Tools

Read — always available

| Tool | Permission | What it does | |---|---|---| | txadmin_whoami | — | Which account, which permissions, which tools are active. Start here when something is missing | | txadmin_status | — | Server up/down, scheduled restart, txAdmin/FXServer versions, host CPU and memory | | txadmin_online_players | — | Live playerlist with server IDs and licenses | | txadmin_find_player | — | Search the player database by name, notes or identifier — includes offline players | | txadmin_player_info | — | Full profile: identifiers, playtime, notes, and complete ban/warning history | | txadmin_history_search | — | Every ban and warning, filterable by type, admin or reason | | txadmin_read_console | console.view | Recent FXServer console with grep. The tool for diagnosing crashes and script errors | | txadmin_read_server_log | server.log.view | In-game events: chat, joins, drops, deaths, explosions | | txadmin_player_drops | — | Disconnect reasons grouped by cause — "why are players crashing" |

Write — default tier

| Tool | Permission | What it does | |---|---|---| | txadmin_announce | announcement | Broadcast to all players (also posts to Discord if the panel has it configured) | | txadmin_player_action | per-action | Direct message, warn, save an admin note, set whitelist | | txadmin_resource_control | commands.resources | ensure, restart, refresh — the safe resource iteration verbs |

Admin — requires TXADMIN_MODE=admin

| Tool | Permission | What it does | |---|---|---| | txadmin_player_punish | players.ban | Kick or ban. Bans require an explicit duration — never permanent by omission | | txadmin_revoke_action | players.ban | Undo a ban or warning by its action ID | | txadmin_server_control | control.server | Start/stop/restart FXServer, stop/start a resource, kick everyone | | txadmin_console_command | console.write | Arbitrary FXServer console execution. Effectively root on the game server |

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

| Symptom | Cause | |---|---| | Missing HTTP header 'x-txadmin-csrftoken' | A reverse proxy in front of txAdmin is stripping the header. Configure it to pass x-txadmin-* through | | did not return JSON | TXADMIN_URL isn't a txAdmin panel, or points at the game port (30120) instead of the panel port (40120) | | Too many attempts | txAdmin's login limiter. Wait it out — retrying extends the block, and it locks you out of the browser panel too | | A console tool is missing | The account lacks console.view. Run txadmin_whoami to confirm | | FXServer is not running | The game server is stopped. Start it in txAdmin, or use txadmin_server_control in admin mode |

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