openmonetis-mcp

Servidor MCP para o OpenMonetis. Permite que agentes de IA leiam e alterem seus dados financeiros conversando com a API oficial do OpenMonetis — sem acesso direto ao banco e sem duplicar regra de negócio.

• Cliente HTTP puro da API pública do OpenMonetis (/openapi.json é o contrato).

• Autenticação por sessão Better Auth (email + senha), com renovação automática em 401.

• 75 ferramentas de leitura e escrita, com dry-run obrigatório nas alterações (14 no perfil core).

• Dois transportes: stdio (local) e Streamable HTTP (remoto, protegido por bearer token).

Como funciona

cliente MCP  ──stdio/HTTP──▶  openmonetis-mcp  ──HTTP + cookie──▶  API do OpenMonetis

1. No primeiro uso o servidor faz POST {OPENMONETIS_URL}/api/auth/sign-in/email com OPENMONETIS_EMAIL/OPENMONETIS_PASSWORD e mantém o cookie de sessão em memória.

2. Se a API responder 401, a sessão é renovada uma única vez e a requisição é repetida.

3. Toda resposta é desembrulhada do envelope { "data": ..., "error": null } da API.

O servidor nunca lê o banco, nunca importa código do OpenMonetis e nunca imprime credenciais.

Related MCP server: OpenBudget MCP Server

Instalação

# direto do GitHub
npx -y github:Welington98/openmonetis-mcp

# ou a partir do código
git clone git@github.com:Welington98/openmonetis-mcp.git
cd openmonetis-mcp
pnpm install
pnpm build
node dist/index.js

Cofre de credenciais (recomendado)

Em vez de espalhar e-mail e senha no JSON de cada cliente MCP, guarde-os uma vez no cofre local:

npx -y github:Welington98/openmonetis-mcp auth set
# URL do OpenMonetis: https://financas.exemplo.com/api-proxy
# E-mail: voce@exemplo.com
# Credencial de voce@exemplo.com (não será exibida): ********
# Login validado. Guardado em: Keychain do macOS.

O login é validado antes de salvar — se a credencial estiver errada, nada é gravado.

Onde fica:

Precedência: OPENMONETIS_EMAIL/OPENMONETIS_PASSWORD do ambiente sempre ganham do cofre. Com o cofre preenchido, os exemplos de cliente abaixo podem omitir essas duas variáveis.

# provisionamento sem interação
printf '%s' "$SENHA" | openmonetis-mcp auth set \
  --url=https://financas.exemplo.com/api-proxy --email=voce@exemplo.com --password-stdin

Configuração

Copie .env.example para .env e preencha pelo menos OPENMONETIS_URL e as credenciais.

¹ Ou defina OPENMONETIS_COOKIE. ² Obrigatório quando o host HTTP não é loopback.

Perfil de catálogo (core vs full)

full é o padrão e expõe as 75 ferramentas. core reduz o catálogo a 14 leituras (get_dashboard_overview, get_dashboard_attention, get_dashboard_snapshot, list_transactions, get_transaction, list_accounts, list_cards, list_invoices, list_bills, list_budgets, list_goals, list_categories, list_tags, list_people), que cobrem a rotina do mês sem as ferramentas avançadas nem as de escrita.

Use core quando o agente tem orçamento de contexto apertado ou quando o cliente cobra o tools/list a cada sessão: o catálogo cai de ~78 KB (~20 mil tokens) para ~12 KB (~3,2 mil tokens), uma economia de ~84%. Nesse perfil as instructions do servidor avisam que o catálogo está reduzido; basta definir OPENMONETIS_MCP_TOOLS=full para reabrir tudo.

O cache e o retry são transparentes. Se precisar ver dados que acabaram de mudar, reduza OPENMONETIS_MCP_CACHE_TTL_MS (ou use 0 para desligar o cache). Escritas sempre invalidam o cache do recurso alterado, então o fluxo "alterar e reler" continua correto.

Qual URL usar

Clientes

Claude Desktop / Claude Code

{
  "mcpServers": {
    "openmonetis": {
      "command": "npx",
      "args": ["-y", "github:Welington98/openmonetis-mcp"],
      "env": {
        "OPENMONETIS_URL": "https://financas.exemplo.com/api-proxy",
        "OPENMONETIS_EMAIL": "voce@exemplo.com",
        "OPENMONETIS_PASSWORD": "sua-senha",
        "OPENMONETIS_MCP_WRITES": "confirm"
      }
    }
  }
}

claude mcp add openmonetis \
  -e OPENMONETIS_URL=https://financas.exemplo.com/api-proxy \
  -e OPENMONETIS_EMAIL=voce@exemplo.com \
  -e OPENMONETIS_PASSWORD=sua-senha \
  -- npx -y github:Welington98/openmonetis-mcp

opencode

{
  "mcp": {
    "openmonetis": {
      "type": "local",
      "enabled": true,
      "command": ["npx", "-y", "github:Welington98/openmonetis-mcp"],
      "environment": {
        "OPENMONETIS_URL": "https://financas.exemplo.com/api-proxy",
        "OPENMONETIS_EMAIL": "voce@exemplo.com",
        "OPENMONETIS_PASSWORD": "sua-senha"
      }
    }
  }
}

Codex CLI

[mcp_servers.openmonetis]
command = "npx"
args = ["-y", "github:Welington98/openmonetis-mcp"]
env = { OPENMONETIS_URL = "https://financas.exemplo.com/api-proxy", OPENMONETIS_EMAIL = "voce@exemplo.com", OPENMONETIS_PASSWORD = "sua-senha" }

Hermes Agent (Nous Research)

O Hermes Agent tem suporte nativo a MCP e normalmente roda em container, então o caminho recomendado é HTTP, não stdio. Coloque o MCP na mesma rede Docker do Hermes e aponte a URL para o nome do serviço.

1. Serviço no mesmo docker-compose.yml do Hermes

services:
  openmonetis-mcp:
    image: ghcr.io/welington98/openmonetis-mcp:0.2.0
    restart: unless-stopped
    environment:
      # OpenMonetis na mesma máquina do host Docker:
      OPENMONETIS_URL: http://host.docker.internal:7002/api-proxy
      OPENMONETIS_ALLOW_INSECURE: "1"
      OPENMONETIS_ORIGIN: http://localhost:7002
      OPENMONETIS_EMAIL: demo@openmonetis.local
      OPENMONETIS_PASSWORD: demo2026
      OPENMONETIS_MCP_HTTP_HOST: 0.0.0.0
      MCP_HTTP_TOKEN: ${OPENMONETIS_MCP_TOKEN}
      # Exportações e uploads precisam de volume próprio (ver "Arquivos locais")
      OPENMONETIS_EXPORT_DIR: /data/exports
    volumes:
      - ./openmonetis-exports:/data/exports
    extra_hosts:
      - "host.docker.internal:host-gateway"

Se o OpenMonetis for público em HTTPS, use OPENMONETIS_URL: https://seu-dominio/api-proxy e remova OPENMONETIS_ALLOW_INSECURE e OPENMONETIS_ORIGIN.

2. Token no .env do projeto do Hermes

OPENMONETIS_MCP_TOKEN=$(openssl rand -hex 32)

3. hermes-data/config.yaml

mcp_servers:
  openmonetis:
    url: "http://openmonetis-mcp:7317/mcp"
    headers:
      Authorization: "Bearer ${OPENMONETIS_MCP_TOKEN}"
    timeout: 120          # export, importação e diagnóstico podem passar dos 20s padrão
    lazy: true            # registra as ferramentas pelo cache e conecta no primeiro uso
    tools:
      include:
        - get_dashboard_overview
        - get_dashboard_attention
        - list_transactions
        - get_transaction
        - list_accounts
        - list_bills
        - list_invoices
        - list_budgets
        - list_goals
        - list_categories
        - list_people
        - get_financial_distribution
        - get_category_trends
        - list_commitments
        - create_transaction
        - settle_transactions
        - export_transactions

${OPENMONETIS_MCP_TOKEN} é resolvido por Hermes a partir de ~/.hermes/.env; no container, esse arquivo fica em hermes-data/.env.

4. Aplicar e verificar

hermes mcp test openmonetis     # testa conexão e lista as ferramentas
# em uma sessão aberta:
/reload-mcp

O Hermes registra cada ferramenta com o prefixo do servidor: list_transactions aparece como mcp_openmonetis_list_transactions. O hermes gateway run também recarrega sozinho quando o config.yaml muda (cerca de um minuto).

Escolha do filtro de ferramentas

    tools:
      exclude:
        - delete_transaction
        - delete_attachment
        - delete_inbox_rule
        - delete_import_batch
        - revoke_person_connection
        - delete_person_settlement
        - delete_ai_chat
        - undo_installment_anticipation

Mantenha OPENMONETIS_MCP_WRITES=confirm (padrão): o agente recebe dry-run e só aplica com confirm: true, o que combina com a aprovação de comandos do Hermes.

Se o Hermes estiver fora do Docker (CLI/desktop nativo), use stdio como em qualquer cliente:

mcp_servers:
  openmonetis:
    command: "npx"
    args: ["-y", "github:Welington98/openmonetis-mcp"]
    env:
      OPENMONETIS_URL: "http://localhost:7002/api-proxy"
      OPENMONETIS_EMAIL: "demo@openmonetis.local"
      OPENMONETIS_PASSWORD: "demo2026"
      OPENMONETIS_ORIGIN: "http://localhost:7002"

Transporte HTTP

OPENMONETIS_MCP_HTTP_HOST=0.0.0.0 \
OPENMONETIS_MCP_HTTP_PORT=7317 \
MCP_HTTP_TOKEN=um-token-longo-e-aleatorio \
OPENMONETIS_URL=https://financas.exemplo.com/api-proxy \
OPENMONETIS_EMAIL=voce@exemplo.com \
OPENMONETIS_PASSWORD=sua-senha \
node dist/http.js

• Endpoint MCP: POST http://host:7317/mcp com Authorization: Bearer <MCP_HTTP_TOKEN>.

• Health check: GET http://host:7317/health.

• Modo stateless e single-user: um processo atende uma credencial. Para várias pessoas, rode um processo por conta (ou aguarde suporte a token de API por usuário no backend).

Docker

O Dockerfile gera uma imagem enxuta (multi-stage, node:22-alpine, usuário node) cujo entrypoint é o transporte HTTP. Para subir como serviço, veja Rodando como serviço (container).

Rodando como serviço (container)

O transporte stdio não faz sentido dentro de um container: o serviço expõe Streamable HTTP em /mcp, com health check em /health e autenticação por [BEARER_REDACTED].

docker compose (recomendado)

cp .env.example .env              # preencha OPENMONETIS_URL, credenciais e MCP_HTTP_TOKEN
docker compose pull && docker compose up -d   # usa a imagem publicada
# ou, para construir localmente:
# docker compose up -d --build
docker compose logs -f

O compose.yaml já traz restart: unless-stopped, healthcheck, read_only, no-new-privileges, rotação de logs e publicação apenas em loopback (127.0.0.1:7317).

docker compose ps          # status + healthy
docker compose pull && docker compose up -d   # atualizar a imagem
docker compose down        # parar

docker run

docker build -t openmonetis-mcp .

docker run -d --name openmonetis-mcp \
  --restart unless-stopped \
  -p 127.0.0.1:7317:7317 \
  --add-host=host.docker.internal:host-gateway \
  -e MCP_HTTP_TOKEN=um-token-longo-e-aleatorio \
  -e OPENMONETIS_URL=https://financas.exemplo.com/api-proxy \
  -e OPENMONETIS_EMAIL=voce@exemplo.com \
  -e OPENMONETIS_PASSWORD=sua-senha \
  openmonetis-mcp

Imagem publicada

docker pull ghcr.io/welington98/openmonetis-mcp:latest

O pacote é público (pull anônimo funciona). A publicação é feita pelo workflow .github/workflows/release-image.yml, disparado por tag vX.Y.Z ou execução manual. Tags SemVer só aparecem quando a tag Git é criada; execuções manuais publicam apenas latest.

Para fixar uma versão em produção, use um digest ou a tag exata:

services:
  openmonetis-mcp:
    image: ghcr.io/welington98/openmonetis-mcp:0.1.0

Container falando com OpenMonetis no mesmo host

Dentro do container, localhost é o próprio container. Aponte para o host com host.docker.internal — e, como esse tráfego é http://, libere explicitamente:

OPENMONETIS_URL=http://host.docker.internal:7002/api-proxy
OPENMONETIS_ALLOW_INSECURE=1        # necessário: http:// não-loopback
OPENMONETIS_ORIGIN=http://localhost:7002   # precisa estar em trustedOrigins (WEB_URL)
MCP_HTTP_TOKEN=um-token-longo-e-aleatorio

OPENMONETIS_ORIGIN é obrigatório nesse caso porque o default é a origem de OPENMONETIS_URL (http://host.docker.internal:7002), que não consta em trustedOrigins do Better Auth. Se o OpenMonetis for público em HTTPS, nenhum desses três ajustes é necessário.

Se o OpenMonetis também roda em Docker Compose, o mais limpo é colocar os dois na mesma rede e usar o nome do serviço:

services:
  openmonetis-mcp:
    networks: [openmonetis]
  # ...
networks:
  openmonetis:
    external: true

Com OPENMONETIS_URL=http://api:7001 (ou http://web:7002/api-proxy) e OPENMONETIS_ALLOW_INSECURE=1.

Acesso remoto com reverse proxy

Mantenha a porta publicada em loopback e exponha via proxy com TLS:

location /mcp {
    proxy_pass http://127.0.0.1:7317/mcp;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_buffering off;
    proxy_read_timeout 3600s;
}

O Authorization do cliente atravessa o proxy; o token do OpenMonetis nunca é exposto, porque vive apenas na memória do container.

Iniciar com o host

restart: unless-stopped já cobre reboot desde que o Docker esteja habilitado no boot (systemctl enable docker). Para amarrar explicitamente ao ciclo do systemd:

# /etc/systemd/system/openmonetis-mcp.service
[Unit]
Description=OpenMonetis MCP
Requires=docker.service
After=docker.service network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/openmonetis-mcp
ExecStart=/usr/bin/docker compose up -d --remove-orphans
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now openmonetis-mcp

Releases

O versionamento é automático, dirigido por Conventional Commits via semantic-release. Cada push na main executa o workflow release, que calcula a próxima versão, atualiza package.json e CHANGELOG.md, cria a tag vX.Y.Z, publica o GitHub Release e então gera a imagem com as tags SemVer.

Regras do fluxo:

• Nunca edite a versão em package.json nem crie tags à mão: ambas são derivadas dos commits.

• src/version.ts lê a versão do package.json em tempo de build (define do tsup), então /health e o handshake MCP sempre reportam a versão publicada.

• O commit de release (chore(release): x.y.z [skip ci]) não dispara a própria pipeline.

• A imagem recebe <versão>, <major>.<minor> e latest na mesma execução.

• Para republicar a imagem sem novo release: Actions → release image → Run workflow (opcionalmente informando a versão, ex.: 0.1.0).

Repositório ainda sem tag? O semantic-release parte de 1.0.0 quando não existe tag anterior, por isso a primeira tag (v0.1.0) precisa existir antes de automatizar.

Ferramentas

Leitura

| list_inbox_items | Notificações capturadas, por status e app de origem. | | get_inbox_snapshot | Contagens e últimos itens pendentes da caixa de entrada. | | list_inbox_rules | Regras que categorizam capturas automaticamente. | | suggest_inbox_item | Categoria/pessoa que as regras aplicariam a um item. | | preview_transaction_import | Lê OFX/CSV/XLSX por caminho local e mostra o que seria importado. | | export_transactions | Exporta CSV/XLSX para arquivo no host e devolve o caminho. | | get_import_template | Baixa a planilha modelo de importação. | | list_transaction_attachments / list_attachments | Anexos de uma transação ou do mês. | | get_attachment_download_url | URL assinada e temporária de um anexo. | | list_installments | Séries parceladas do mês com progresso e parcelas pendentes (detail: "compact" por padrão). | | quote_installments | Cotação da antecipação de parcelas para uma fatura. | | list_person_connections / list_person_invitations | Conexões e convites entre pessoas. | | list_person_settlements / get_person_balance | Acertos e saldo com cada pessoa. | | get_ai_status | Provedores de IA, ferramentas e escopos de dados compartilhados. | | list_ai_diagnoses / get_ai_diagnosis | Diagnósticos financeiros gerados por IA. | | list_ai_chats / get_ai_chat | Conversas com o assistente financeiro. |

Escrita

Arquivos locais

export_transactions, get_import_template e upload_attachment leem/gravam no host onde o MCP roda — no transporte stdio é a sua máquina; no modo HTTP é o container (por isso o volume em compose.yaml e no exemplo do Hermes). Nesse caso, monte um volume para o diretório de exportação:

    volumes:
      - ./exports:/home/node/Downloads/openmonetis-mcp

e defina OPENMONETIS_EXPORT_DIR=/home/node/Downloads/openmonetis-mcp.

Modos de escrita

No dry-run de uma exclusão o servidor busca a transação antes, para mostrar nome, valor e data do alvo. Ferramentas destrutivas também enviam destructiveHint: true ao cliente MCP, permitindo que ele peça aprovação ao usuário.

Segurança

• Credenciais: a senha é enviada apenas ao endpoint de login da sua instalação; o cookie de sessão fica em memória e nunca é gravado em disco ou logado. Prefira op run (1Password), Keychain ou variáveis de ambiente do cliente MCP a arquivos .env versionados.

• Menor privilégio: read-only ou confirm são o padrão. full é opt-in.

• Rede: http:// é aceito apenas para loopback; para host remoto o servidor exige https:// (ou OPENMONETIS_ALLOW_INSECURE=1, desencorajado).

• HTTP remoto: sem MCP_HTTP_TOKEN o servidor só sobe em loopback. A comparação do token é feita em tempo constante.

• Sessão: a duração é a da instalação (AUTH_SESSION_EXPIRES_IN_DAYS, padrão 30 dias). Revogar a sessão na web (Ajustes → Segurança) invalida o MCP imediatamente.

Desenvolvimento

pnpm install
pnpm dev          # stdio via tsx
pnpm dev:http     # HTTP via tsx
pnpm lint         # Biome
pnpm typecheck    # tsc --noEmit
pnpm test         # node:test com API fake local
pnpm build        # tsup → dist/
pnpm check        # lint + typecheck + test + build
pnpm bench:tools  # custo do tools/list nos perfis core e full (bytes e tokens aproximados)

# contrato: gera tipos + snapshot a partir da instância e valida as rotas usadas
OPENMONETIS_URL=http://localhost:7002/api-proxy pnpm gen:contract
pnpm check:contract                                  # offline, contra contract/
OPENMONETIS_URL=http://localhost:7002/api-proxy pnpm check:contract   # + instância viva

Os testes unitários sobem uma API fake em 127.0.0.1 (sem rede externa) e exercitam login, renovação de sessão, envelope de erro, paginação, dry-run, gate de escrita e o cofre de credenciais.

O workflow e2e vai além: em cada push/PR ele sobe Postgres + migrações + a imagem oficial da API, cria uma conta, popula 6 meses de dados e roda as 75 ferramentas de verdade (SMOKE_WRITES=1), além de falhar se contract/ divergir do /openapi.json da versão usada. É o que pega mudanças de contrato antes de chegarem ao usuário.

Contrato

contract/openapi.snapshot.json (especificação) e contract/openapi.d.ts (tipos) são gerados por pnpm gen:contract e versionados. A lista de rotas em scripts/check-contract.ts é tipada por eles: um path ou método que deixe de existir quebra o tsc. Quando a API mudar, rode pnpm gen:contract e commite o diff.

Troubleshooting

Limitações

• Single-user por processo; não há multi-tenancy nem OAuth por usuário.

• Cobre 79 dos ~170 endpoints da API. Fora do escopo: configuração de provedores de IA (login OAuth), regras de vencimento, importação de despesas externas, antecipação de faturas, device tokens, releases, notificações individuais e o CRUD completo de preferências.

• Chat com IA não é exposto: /ai-chats/{id}/messages responde em SSE e o streaming não cabe bem no protocolo de ferramentas. Diagnósticos (create_ai_diagnosis) funcionam normalmente.

• Anexos exigem storage S3 configurado na instância; sem isso o upload retorna 503.

• @openmonetis/* não é importado de propósito: este repositório é independente do monorepo, e o contrato é a API HTTP pública.

Contribuindo

A main tem histórico protegido por ruleset: force-push, deleção e recriação do branch são bloqueados. Mudanças entram por pull request com os checks check (CI) e e2e verdes — o semantic-release continua commitando direto na main porque o repositório é de usuário, onde o GitHub não permite dar bypass ao Actions.

Para exigir PR de forma impositiva (e não por convenção), é preciso um token de release (PAT ou GitHub App) com bypass de administrador — o semantic-release passaria a usar esse token.

git switch -c feat/minha-mudanca
# ... commits em Conventional Commits ...
pnpm check            # lint + typecheck + test + build
git push -u origin feat/minha-mudanca
gh pr create --fill

Regras do fluxo:

• Um PR = um assunto. Título em Conventional Commits, porque é ele que define a versão no squash.

• Mudou endpoint ou schema? Rode pnpm gen:contract e commite contract/ no mesmo PR — o job e2e falha se o contrato divergir da API.

• Nova ferramenta de escrita precisa de plan() com dry-run legível; sem isso o revisor humano não consegue avaliar o que o agente faria.

• Nunca inclua credenciais. Use openmonetis-mcp auth set localmente, nunca no repositório.

Licença

MIT — veja LICENSE.