Skip to main content
Glama

yafmcp

Servidor MCP para operar um servidor FiveM: o agente manda um comando, o comando entra no console do FXServer e a saída do console volta como resposta.

Funciona com qualquer cliente MCP — Claude Code, Hermes, Codex, OpenCode, ou o que vier depois — porque é MCP por stdio puro (e HTTP streamable quando você quiser).

Como ele fala com o servidor

Pelo live console do txAdmin (v7/v8): login por senha em /auth/password, sessão guardada em cookie, e o comando vai pelo socket.io na sala liveconsole, exatamente como a aba Live Console do painel faz. A saída é capturada do stream consoleData, limpa de ANSI e devolvida.

Não precisa de rcon_password, não precisa reiniciar o servidor, não precisa de acesso ao container.

O socket.io do txAdmin só responde por long-polling: o servidor HTTP que escuta na porta do painel roteia /socket.io para engine.handleRequest, e não trata upgrade de websocket. O cliente aqui já vem fixado em polling por causa disso.

Related MCP server: factorio-mcp

Instalação

Pelo npm, sem clonar nada:

npx -y yafmcp --setup     # grava as credenciais do txAdmin
npx -y yafmcp --doctor    # confere a conexão

Ou do repositório, para mexer no código:

git clone https://github.com/ggfto/yafmcp.git
cd yafmcp
pnpm install
pnpm run setup     # pergunta URL do txAdmin, usuário e senha; grava 600 em ~/.config/yafmcp/config.json
pnpm run doctor    # loga, conecta no console e roda um "version"

Requer Node 18+ (testado no 22) e um admin do txAdmin com permissão de console (console.view + console.write; o master já tem).

Configuração

~/.config/yafmcp/config.json (ou variáveis de ambiente, que têm precedência):

Campo

Env

Padrão

txadminUrl

FIVEM_TXADMIN_URL

http://127.0.0.1:40120

serverUrl

FIVEM_SERVER_URL

http://127.0.0.1:30120

username

FIVEM_TXADMIN_USER

—

password

FIVEM_TXADMIN_PASS

—

quietMs

FIVEM_QUIET_MS

900 — silêncio no console que fecha a captura

timeoutMs

FIVEM_TIMEOUT_MS

10000 — teto da captura

scrollback

—

2000 linhas guardadas em memória

logsDir

FIVEM_LOGS_DIR

vazio — acha txData/<perfil>/logs pelo FXServer rodando na mesma máquina

Registrando nos agentes

node src/register.js          # registra em todos os clientes presentes na máquina
node src/register.js --print  # só imprime os trechos, você cola onde quiser

Ou na mão:

Em todos os exemplos abaixo, npx -y yafmcp e node /caminho/yafmcp/src/index.js são intercambiáveis — o primeiro dispensa clone, o segundo usa a sua cópia local.

# Claude Code
claude mcp add --scope user fivem -- npx -y yafmcp
# Codex — ~/.codex/config.toml
[mcp_servers.fivem]
command = "node"
args = ["/caminho/yafmcp/src/index.js"]
// OpenCode — ~/.config/opencode/opencode.json
{ "mcp": { "fivem": { "type": "local", "command": ["node", "/caminho/yafmcp/src/index.js"], "enabled": true } } }
# Hermes — ~/.hermes/config.yaml
mcp_servers:
  fivem:
    command: node
    args:
      - /caminho/yafmcp/src/index.js
    enabled: true

Ferramentas

Ferramenta

O que faz

fivem_command

Executa qualquer comando no console e devolve a saída. Para resource, ensure <resource> é o padrão (inicia ou reinicia); refresh antes se o resource é novo no disco. timeoutMs, quietMs e timestamps são opcionais.

fivem_console

Últimas linhas do console capturadas pela sessão, com filter por regex.

fivem_logs

Arquivos de log do txAdmin: fxserver.log (dia inteiro, boots anteriores), dias rotacionados e admin.log. sinceBoot corta no último start, filter por regex, list mostra os arquivos. Só lê arquivo de dentro da pasta de logs.

fivem_status

No ar?, hostname, jogadores, game build, nº de resources.

fivem_players

Jogadores online com id, ping e identificadores.

fivem_server_control

start / stop / restart do processo do servidor (derruba quem estiver online).

> recarrega o resource mri_Qadmin
  fivem_command("ensure mri_Qadmin")
  $ ensure mri_Qadmin
  [           resources] Stopping resource mri_Qadmin
  [    c-scripting-core] Creating script environments for mri_Qadmin
  [           resources] Started resource mri_Qadmin

Outros modos

node src/index.js                   # MCP stdio (o normal)
node src/index.js --http --port 8765  # MCP streamable HTTP em /mcp, para clientes que falam por URL
node src/index.js --exec "refresh"  # um comando direto pelo terminal, sem agente no meio
node src/index.js --logs "error"    # fxserver.log desde o último boot, filtrado
node src/index.js --doctor          # diagnóstico da conexão

Quem usa o Clink pode criar um tipo de agente FiveM Ops — mission + rule sheet — que nasce sabendo operar o servidor:

node tools/clink-agent.js
clink new "FiveM Ops" "FiveM"

FIVEM_DEFAULT_PATH escolhe a pasta em que esse agente abre (padrão ~/fx-panel).

Segurança

Nenhum comando é bloqueado: quem tem o MCP tem o console do servidor inteiro. A senha fica só no arquivo de config (modo 600) ou no ambiente — nunca no repositório, nunca no prompt do agente. Se isso for demais para o seu caso, dê ao MCP um admin do txAdmin com permissões reduzidas: a checagem de permissão é feita pelo próprio txAdmin.

Publicando o pacote

Mesmo esquema do mri-ui-kit, sem passo manual:

  • Commits no padrão Conventional Commits — é deles que sai a versão. fix: vira patch, feat: vira minor, feat!:/BREAKING CHANGE vira major; chore:, ci:, docs:, test: não geram versão.

  • release.yml roda a cada push na main: testa e chama o semantic-release, que bumpa o package.json, escreve o CHANGELOG.md, commita chore(release): x.y.z e cria a tag e a release no GitHub. Não publica nada.

  • publish.yml roda logo depois (ou na mão, pela aba Actions) e publica no npmjs.com por trusted publishing (OIDC), sem NPM_TOKEN. Se a versão do package.json já está no npm, não faz nada.

Configuração única no npmjs.com: pacote yafmcp → Settings → Trusted publisher → GitHub Actions, repositório mri-Qbox-Brasil/yafmcp, workflow publish.yml.

ci.yml roda os testes em push e PR, no Node 20, 22 e 24.

Licença

MIT.

Available Tools

6 tools
fivem_commandExecutar comando no console do FiveMA

Executa um comando no console do FXServer e devolve o que o console imprimiu. Aceita qualquer comando do servidor. Para (re)carregar um resource use "ensure ": ele inicia o que está parado e reinicia o que está rodando, sem precisar saber o estado antes — "start" e "restart" só valem quando falhar em um dos dois casos é justamente o que você quer. Resource novo no disco ou manifest alterado pede "refresh" antes. Também aceita stop, say, kick, set/setr , etc. A captura fecha quando o console fica quieto; comandos que demoram para responder pedem timeoutMs maior.

Inputs: command (required), quietMs, timeoutMs, timestamps.

fivem_consoleLer o console do FiveMA

Últimas linhas do console do servidor capturadas por esta sessão, com filtro opcional por regex. Use depois de um comando que continua imprimindo, ou para investigar erros.

Inputs: lines, filter.

fivem_logsLer os arquivos de log do servidorA

Lê os arquivos de log do txAdmin (txData//logs): fxserver.log é o console do dia inteiro, inclusive de antes desta sessão e de boots anteriores; os dias passados ficam em fxserver_AAAA-MM-DD_*.log, e admin.log tem as ações dos admins. Use sinceBoot para ver só o que veio depois do último start do servidor, filter (regex, sem diferenciar maiúsculas) para achar erros, e list para ver os arquivos.

Inputs: file, list, lines, filter, +1 more.

fivem_playersJogadores conectadosA

Lista os jogadores online com id, nome, ping e identificadores.

Inputs: no named parameters.

fivem_server_controlControlar o processo do servidorA

start, stop ou restart do FXServer pelo txAdmin. Derruba todo mundo que estiver online — para recarregar um resource use fivem_command com "ensure ".

Inputs: action (required).

fivem_statusStatus do servidor FiveMA

Estado do servidor: se está no ar, hostname, jogadores online, slots, game build e quantidade de resources. Lê os endpoints públicos do próprio FXServer.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 6 tools

    Disambiguation4/5

    The tools mostly target distinct surfaces: command execution, log files, server lifecycle, live console tail, player list, and status. The main risk is overlap between fivem_command (which already returns console output), fivem_console, and fivem_logs, plus fivem_status duplicating the player count from fivem_players, but descriptions explicitly steer usage (e.g. server_control pointing to 'ensure' via fivem_command, console for output after a long-running command).

    Naming Consistency4/5

    All names share a consistent fivem_ prefix in snake_case, which makes the set predictable. The only minor deviation is that names are noun/resource-based (fivem_console, fivem_logs, fivem_status) rather than a uniform verb_noun pattern, but they remain readable and grouped coherently.

    Tool Count5/5

    Six tools is well-scoped for a FiveM/txAdmin server-management server, with each tool covering a clear, non-redundant facet (execute, logs, lifecycle, console, players, status). Nothing feels padded or missing at the count level.

    Completeness4/5

    The surface covers the core operational lifecycle: status inspection, player listing, command execution (including resource ensure/refresh), console tailing, and full server start/stop/restart. Gaps are minor, such as no direct resource/file or manifest editing and no dedicated player-management action, though these can be worked around via fivem_command.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables control and inspection of a Factorio 2.0 server via RCON, with tools for administration, player management, game state queries, and Lua execution.
      19
      ISC
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to read and administer FiveM/RedM game servers via txAdmin, supporting queries about server status, players, bans, and actions like announcements, resource control, and bans.
      15 npm
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables interaction with a Minecraft server using Skript scripting language. Provides tools for checking and reloading Skript files, executing Minecraft commands, and retrieving server logs.
      5
      MIT