Actual Budget

Integre o Actual Budget com assistentes LLM para gerenciar suas finanças pessoais.

GitHub
234

Documentação

Servidor MCP do Actual Budget

Servidor MCP para integrar o Actual Budget com Claude e outros assistentes de LLM.

Visão Geral

O Servidor MCP do Actual Budget permite que você interaja com seus dados financeiros pessoais do Actual Budget usando linguagem natural por meio de LLMs. Ele expõe suas contas, transações e métricas financeiras através do Model Context Protocol (MCP).

Recursos

Recursos

  • Listagem de Contas - Navegue por todas as suas contas com seus saldos
  • Detalhes da Conta - Veja informações detalhadas sobre contas específicas
  • Histórico de Transações - Acesse dados de transações com detalhes completos

Ferramentas

Gerenciamento de Transações e Contas

  • get-transactions - Recupere e filtre transações por conta, data, valor, categoria ou beneficiário
  • create-transaction - Crie uma nova transação em uma conta com categoria, beneficiário e notas opcionais
  • update-transaction - Atualize uma transação existente com nova categoria, beneficiário, notas ou valor
  • get-accounts - Recupere uma lista de todas as contas com seu saldo atual e ID
  • balance-history - Veja as mudanças de saldo da conta ao longo do tempo

Relatórios e Análises

  • spending-by-category - Gere detalhamentos de gastos categorizados por tipo
  • monthly-summary - Obtenha métricas mensais de receitas, despesas e economia
  • budget-vs-actual - Compare valores orçados com gastos reais por categoria
  • net-worth - Acompanhe ativos, passivos e patrimônio líquido em todas as contas ao longo do tempo
  • category-trends - Veja como os gastos em cada categoria variam mês a mês, com direção de tendência
  • spending-by-payee - Classifique os beneficiários pelo quanto foi gasto com (ou recebido de) cada um
  • cash-flow - Reporte receitas, despesas e fluxo de caixa líquido por mês ou semana

As cinco ferramentas acima retornam JSON em vez de markdown, para que os valores permaneçam legíveis por máquina. Cada valor é um número inteiro de centavos, e cada resposta inclui um campo amountsIn descrevendo as convenções de sinal que utiliza.

Relatórios Personalizados e Painéis

  • get-custom-reports - Recupere todos os relatórios personalizados salvos da seção Relatórios
  • create-custom-report - Crie um relatório personalizado salvo
  • update-custom-report - Atualize campos em um relatório personalizado salvo, mantendo o restante inalterado
  • delete-custom-report - Exclua um relatório personalizado salvo
  • get-dashboards - Recupere todas as páginas do painel e os widgets dispostos nelas
  • add-dashboard-widget - Adicione um widget a uma página do painel
  • update-dashboard-widget - Atualize a configuração, posição ou tamanho de um widget
  • remove-dashboard-widget - Remova um widget de sua página
  • organize-dashboard - Reposicione e redimensione vários widgets de uma vez
  • create-dashboard-page / rename-dashboard-page / delete-dashboard-page - Gerencie páginas do painel

Categorias

  • get-grouped-categories - Recupere uma lista de todos os grupos de categorias com suas categorias
  • create-category - Crie uma nova categoria dentro de um grupo de categorias
  • update-category - Atualize o nome ou grupo de uma categoria existente
  • delete-category - Exclua uma categoria
  • create-category-group - Crie um novo grupo de categorias
  • update-category-group - Atualize o nome de um grupo de categorias
  • delete-category-group - Exclua um grupo de categorias

Beneficiários

  • get-payees - Recupere uma lista de todos os beneficiários com seus detalhes
  • create-payee - Crie um novo beneficiário
  • update-payee - Atualize os detalhes de um beneficiário existente
  • delete-payee - Exclua um beneficiário

Regras

  • get-rules - Recupere uma lista de todas as regras de transação
  • create-rule - Crie uma nova regra de transação com condições e ações
  • update-rule - Atualize uma regra de transação existente
  • delete-rule - Exclua uma regra de transação

Prompts

  • financial-insights - Gere insights e recomendações com base nos seus dados financeiros
  • budget-review - Analise sua conformidade orçamentária e sugira ajustes

Instalação

Pré-requisitos

Acesso remoto

Baixe a imagem docker mais recente:

docker pull sstefanov/actual-mcp:latest

Configuração local

  1. Clone o repositório:
git clone https://github.com/s-stefanov/actual-mcp.git
cd actual-mcp
  1. Instale as dependências:
npm install
  1. Compile o servidor:
npm run build
  1. Compile a imagem docker local (opcional):
docker build -t <local-image-name> .
  1. Configure as variáveis de ambiente (opcional):
# Path to your Actual Budget data directory (default: ~/.actual)
export ACTUAL_DATA_DIR="/path/to/your/actual/data"

# If using a remote Actual server
export ACTUAL_SERVER_URL="https://your-actual-server.com"
export ACTUAL_PASSWORD="your-password"

# Specific budget to use (optional)
export ACTUAL_BUDGET_SYNC_ID="your-budget-id"

# How long downloaded data stays fresh before the server re-syncs, in ms
# (default: 60000). Use 0 to sync before every call, or -1 to never sync.
export ACTUAL_SYNC_TTL_MS="60000"

Opcional: senha separada para criptografia do orçamento

Se sua configuração do Actual exigir uma senha diferente para desbloquear os dados do orçamento local/criptografado em vez da senha de autenticação do servidor, você pode definir ACTUAL_BUDGET_ENCRYPTION_PASSWORD além de ACTUAL_PASSWORD.

# If server auth and encryption/unlock use different passwords
export ACTUAL_BUDGET_ENCRYPTION_PASSWORD="your-encryption-password"

Ciclo de vida da conexão

O servidor mantém uma conexão compartilhada do Actual durante toda a sua vida útil e serializa as operações do orçamento por meio dela. Os dados baixados são ressincronizados quando excedem a janela de atualização de ACTUAL_SYNC_TTL_MS. Nos modos stdio e HTTP, SIGINT e SIGTERM drenam o trabalho em andamento antes do desligamento do servidor. O Actual não é mais inicializado e desligado a cada chamada de ferramenta.

Semântica de relatórios

  • Saldos e históricos de saldo são limitados até a data de hoje; transações com data futura são excluídas, e a linha do histórico de saldo do mês atual é parcial.
  • Contas fechadas dentro do orçamento permanecem incluídas em relatórios históricos; contas fechadas fora do orçamento permanecem excluídas por padrão.
  • A receita mensal segue os metadados do grupo de receitas do Actual. Reembolsos são compensados com despesas, meses sem atividade contam nas médias, e pares de transferência não categorizados são ignorados.
  • O antigo bucket de Investimentos foi removido dos resumos mensais.

Uso com Claude Desktop

Para usar este servidor com o Claude Desktop, adicione-o à sua configuração do Claude:

No MacOS:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

No Windows:

code %APPDATA%\Claude\claude_desktop_config.json

Adicione o seguinte à sua configuração...

a. Usando Node.js (versão npx):

{
  "mcpServers": {
    "actualBudget": {
      "command": "npx",
      "args": ["-y", "actual-mcp", "--enable-write"],
      "env": {
        "ACTUAL_DATA_DIR": "path/to/your/data",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_SERVER_URL": "http://your-actual-server.com",
        "ACTUAL_BUDGET_SYNC_ID": "your-budget-id"
      }
    }
  }
}

### a. Using Node.js (local only):

```json
{
  "mcpServers": {
    "actualBudget": {
      "command": "node",
      "args": ["/path/to/your/clone/build/index.js", "--enable-write"],
      "env": {
        "ACTUAL_DATA_DIR": "path/to/your/data",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_SERVER_URL": "http://your-actual-server.com",
        "ACTUAL_BUDGET_SYNC_ID": "your-budget-id"
      }
    }
  }
}

b. Usando Docker (imagens locais ou remotas):

{
  "mcpServers": {
    "actualBudget": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/data:/data",
        "-e",
        "ACTUAL_PASSWORD=your-password",
        "-e",
        "ACTUAL_SERVER_URL=https://your-actual-server.com",
        "-e",
        "ACTUAL_BUDGET_SYNC_ID=your-budget-id",
        "sstefanov/actual-mcp:latest",
        "--enable-write"
      ]
    }
  }
}

Após salvar a configuração, reinicie o Claude Desktop.

💡 ACTUAL_DATA_DIR é opcional se você estiver usando ACTUAL_SERVER_URL.

💡 Use --enable-write para habilitar ferramentas de acesso de escrita.

Executando um Servidor SSE

Para expor o servidor em uma porta usando Docker:

docker run -i --rm \
  -p 3000:3000 \
  -v "/path/to/your/data:/data" \
  -e ACTUAL_PASSWORD="your-password" \
  -e ACTUAL_SERVER_URL="http://your-actual-server.com" \
  -e ACTUAL_BUDGET_SYNC_ID="your-budget-id" \
  -e BEARER_TOKEN="your-bearer-token" \
  sstefanov/actual-mcp:latest \
  --sse --enable-write --enable-bearer

⚠️ Importante: Ao usar --enable-bearer, a variável de ambiente BEARER_TOKEN deve ser definida.
🔒 Isso é altamente recomendado se você estiver expondo seu servidor por meio de uma URL pública.

Exemplos de Consultas

Uma vez conectado, você pode fazer perguntas ao Claude como:

  • "Qual é o meu saldo atual da conta?"
  • "Mostre meus gastos por categoria no mês passado"
  • "Quanto gastei com supermercado em janeiro?"
  • "Qual é a minha taxa de economia nos últimos 3 meses?"
  • "Em quais categorias estou gastando demais este mês?"
  • "Como meu patrimônio líquido mudou no último ano?"
  • "Com quais beneficiários gasto mais?"
  • "Meus gastos com supermercado estão tendendo para cima ou para baixo?"
  • "Analise meu orçamento e sugira áreas para melhorar"
  • "Quais relatórios personalizados eu tenho?"
  • "Adicione um widget de patrimônio líquido ao meu painel do Spending Plan"
  • "Reorganize meu painel para que o cartão de fluxo de caixa fique em largura total no topo"

Uso com Codex CLI

Exemplo de configuração do Codex:

Em ~/.codex/config.toml:

[mcp_servers.actual-budget]
url = "http://localhost:3000"

Aponte o Codex para a mesma porta que você passa para npm start -- --sse --port <PORT>.

Desenvolvimento

Para desenvolvimento com recompilação automática:

npm run watch

Testando a conexão com o Actual

Para verificar se o servidor pode se conectar aos seus dados do Actual Budget:

node build/index.js --test-resources

Depuração

Como os servidores MCP se comunicam via stdio, a depuração pode ser desafiadora. Você pode usar o MCP Inspector:

npx @modelcontextprotocol/inspector node build/index.js

Portão de validação E2E

A suíte de testes de ponta a ponta (vitest.e2e.config.ts) inicia um servidor real do Actual Budget em um contêiner Docker (via Testcontainers), semeia um orçamento e o conduz por um cliente MCP real via stdio para verificar se contas, transações, categorias, beneficiários, regras e importações realmente persistem. Requer que o Docker esteja em execução localmente.

No CI, o job e2e-test em .github/workflows/pr-validation.yml só é executado em PRs do release-please (prefixo de branch release-please--) ou quando um PR recebe o rótulo run-e2e — não é executado em todos os PRs por padrão, pois precisa do Docker e leva mais tempo que as verificações padrão.

Para executá-lo localmente:

npm run build && npm run test:e2e

O Docker deve estar instalado e em execução; a suíte de testes baixa e inicia a imagem do servidor Actual automaticamente.

Estrutura do Projeto

  • index.ts - Implementação principal do servidor
  • types.ts - Definições de tipos para respostas e parâmetros da API
  • prompts.ts - Modelos de prompt para interações com LLM
  • utils.ts - Funções auxiliares para formatação de datas e mais

Registro e Descoberta

actual-mcp é publicado no Registro MCP oficial como io.github.s-stefanov/actual-mcp. Os metadados do registro estão em server.json e são publicados automaticamente a cada lançamento (veja .github/workflows/release-please.yml).

Ele anuncia dois transportes no pacote npm — stdio (padrão) e streamable-http (via a flag --sse). (Uma imagem Docker também é publicada, mas ainda não está listada como um pacote do registro.)

Listagens de diretórios pós-lançamento são rastreadas em docs/mcp-registry-checklist.md.

Licença

MIT

Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.