convez.ai
MCP ServerFinanceiroIntermediário
KazeFreeze

Actual Budget MCP

KazeFreeze/actual-budget-mcp

52 tools de orçamento para Claude via MCP com suporte a Docker

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP para integrar Actual Budget com assistentes IA, oferecendo 52 ferramentas para ler, escrever e analisar dados de orçamento. Conecta diretamente ao sync-server oficial usando o SDK @actual-app/api e suporta múltiplos transportes (stdio, HTTP/SSE).

Instalação

$npx convez-ai KazeFreeze/actual-budget-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 2 meses
Versão
v3.2.5
Issues abertas
5
Contribuidores
3

Casos de uso

  • Assistir análise e revisão de orçamentos mensais
  • Automatizar consultas e relatórios de gastos via linguagem natural
  • Integrar dados de orçamento em fluxos de trabalho IA com segurança

Veredito

Solução técnica sólida para expor Actual Budget a assistentes IA com cobertura ampla de tools e transporte seguro. Indicado para quem já usa Actual e quer integração profunda via MCP; requer setup Docker e gerenciamento de chaves de segurança.

README

A tradução para o português deste README ainda está na fila.

actual-budget-mcp

An MCP server for Actual Budget that provides AI assistants with tools to read, write, and analyze your budget data.

Connects directly to your Actual Budget sync server using the official @actual-app/api SDK, deploys as a Docker sidecar.

Features

  • 52 tools -- accounts, transactions, categories, payees, budget months, schedules, rules, notes, tags, utility, and ActualQL query
  • Tags CRUD (NEW in v2) -- full create/read/update/delete for transaction tags
  • Notes (read/write/delete) -- now functional, was broken in v1
  • Raw query power -- query tool with full ActualQL support (filters, aggregates, joins, grouping)
  • 3 MCP resources -- accounts, categories, payees
  • 4 guided prompts -- financial health check, budget review, spending deep dive, ActualQL reference
  • Markdown output -- formatted tables, split transaction rendering, 34-38% fewer tokens than JSON
  • Multiple transports -- stdio (local), Streamable HTTP (remote, recommended), SSE (deprecated, removal targeted v2.1)
  • Security -- multi-key Bearer rotation with entropy enforcement (≥32 chars, ≥16 unique chars), Origin allowlist, helmet headers, per-IP rate limiting, audit logger with sha256 caller-key prefix

Quick Start

Upgrading from v1? See docs/MIGRATION-v1-to-v2.md for the breaking-change guide (env var renames, port change 3001 → 3000, removal of the actual-http-api sidecar).

Docker Compose (recommended)

# Clone the repo
git clone https://github.com/KazeFreeze/actual-budget-mcp.git
cd actual-budget-mcp

# Configure environment (uses the v2 var names: ACTUAL_SERVER_URL,
# ACTUAL_SERVER_PASSWORD, ACTUAL_BUDGET_SYNC_ID, MCP_API_KEYS, ...)
cp .env.example .env

# Start the full stack
docker compose -f docker/docker-compose.production.yml up -d

Using the published image

docker pull ghcr.io/kazefreeze/actual-budget-mcp:latest
docker compose -f docker/docker-compose.production.yml up -d

Local development

npm ci
npm run dev

Configuration

VariableRequiredDefaultDescription
ACTUAL_SERVER_URLYes--Actual sync-server URL (e.g. http://actual-budget:5006)
ACTUAL_SERVER_PASSWORDYes--actual-server login password
ACTUAL_BUDGET_SYNC_IDYes--Budget sync ID (Settings → Advanced → Sync ID)
ACTUAL_BUDGET_ENCRYPTION_PASSWORDIf E2EE--Encryption password (only for E2EE-encrypted budgets)
MCP_API_KEYShttp/sse--Comma-separated bearer tokens. Each ≥32 chars and ≥16 unique chars.
MCP_ALLOWED_ORIGINSNo--Comma-separated allowed Origin headers (recommended in production)
MCP_TRANSPORTNostdioTransport mode: stdio, http, or sse (deprecated)
MCP_PORTNo3000Port for http/sse transport
MCP_RATE_LIMIT_PER_MINNo120Per-IP rate limit (http/sse)
MCP_DATA_DIRNo/var/lib/actual-mcpSDK budget cache directory
MCP_STRICT_VERSION_CHECKNofalseIf true, refuse to start when actual-server major version doesn't match the bundled SDK major. Default: warn and continue.
LOG_LEVELNoinfoLog level: debug, info, warn, error

Architecture

v2: Claude/AI <--MCP--> actual-budget-mcp <----> actual-server
                         (this project)         (sync server)

The MCP server uses @actual-app/api in-process and persists its budget cache to a Docker volume at /var/lib/actual-mcp.

MCP Client Setup

Claude Desktop (stdio)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "actual-budget": {
      "command": "node",
      "args": ["/path/to/actual-budget-mcp/build/src/index.js"],
      "env": {
        "ACTUAL_SERVER_URL": "http://localhost:5006",
        "ACTUAL_SERVER_PASSWORD": "your-actual-server-password",
        "ACTUAL_BUDGET_SYNC_ID": "your-sync-id"
      }
    }
  }
}

Remote (Streamable HTTP, recommended)

Set MCP_TRANSPORT=http and MCP_API_KEYS (comma-separated, each token ≥32 chars and ≥16 unique chars):

{
  "mcpServers": {
    "actual-budget": {
      "url": "http://your-server:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-min-32-chars-and-16-unique"
      }
    }
  }
}

Remote (SSE, deprecated)

SSE transport is still supported through v2.1 for backwards compatibility but is slated for removal. The endpoint is /sse (POSTs to /messages). Responses include Deprecation: true and Sunset headers. Migrate to Streamable HTTP — see docs/MIGRATION-v1-to-v2.md.

Tools

Accounts

ToolDescription
get-accountsList all accounts
get-account-balanceGet current balance for one account
create-accountCreate an on- or off-budget account
update-accountRename or rebalance an account
close-accountClose an account (transferring balance)
reopen-accountReopen a closed account
delete-accountDelete an account

Transactions

ToolDescription
get-transactionsQuery transactions with date / account filters
add-transactionsAdd transactions (no rules / categorization)
import-transactionsImport transactions (with rules + dedupe)
update-transactionUpdate one transaction (supports splits)
delete-transactionDelete a transaction

Categories

ToolDescription
get-categoriesList all categories
get-category-groupsList category groups
create-categoryCreate a category
update-categoryUpdate a category
delete-categoryDelete a category
create-category-groupCreate a category group
update-category-groupUpdate a category group
delete-category-groupDelete a category group

Payees

ToolDescription
get-payeesList all payees
get-common-payeesList the most-used payees
create-payeeCreate a payee
update-payeeUpdate a payee
delete-payeeDelete a payee
merge-payeesMerge one payee into another
get-payee-rulesList rules associated with a payee

Budget

ToolDescription
get-budget-monthGet budget data for a single month
get-budget-monthsList available budget months
set-budget-amountSet the budgeted amount for a category
set-budget-carryoverToggle carryover for a category
hold-budget-for-next-monthHold leftover funds for next month
reset-budget-holdClear a hold-for-next-month flag

Schedules

ToolDescription
get-schedulesList scheduled transactions
create-scheduleCreate a schedule
update-scheduleUpdate a schedule
delete-scheduleDelete a schedule

Rules

ToolDescription
get-rulesList transaction rules
create-ruleCreate a rule
update-ruleUpdate a rule
delete-ruleDelete a rule

Notes

ToolDescription
get-notesGet notes for an entity
set-notesSet notes for an entity
delete-notesDelete notes for an entity

Tags (NEW in v2)

ToolDescription
get-tagsList all transaction tags
create-tagCreate a tag
update-tagUpdate a tag
delete-tagDelete a tag

Utility

ToolDescription
run-bank-syncTrigger bank sync
get-id-by-nameResolve an account / category / payee name to its ID
get-server-versionReport the actual-server version

Query

ToolDescription
queryExecute raw ActualQL queries with full filter, aggregate, and join support

Resources

URIDescription
actual://accountsAll accounts with type and current balance
actual://categoriesFull category tree (groups + categories)
actual://payeesAll payees

Amounts are returned as plain formatted numbers (e.g. 1,250.00). Have your client supply the currency label in its system prompt — for example, add Currency is PHP — display as ₱. to your CLAUDE.md.

Prompts

NameDescription
financial-health-checkGuided savings rate / spending / variance review with recommendations
budget-reviewMonthly budget review with overspent / underspent flags
spending-deep-diveDeep dive into a specific category over a time period
actualql-referenceFull ActualQL syntax reference for the query tool

Development

npm ci                      # Install dependencies
npm run dev                 # Start with hot reload (tsx)
npm test                    # Run unit tests (vitest)
npm run test:integration    # Integration tests against committed budget fixture (real SDK)
npm run test:e2e            # Docker-compose smoke suite (auth, tools, notes round-trip)
npm run lint                # ESLint strict + TypeScript --noEmit
npm run build               # Compile TypeScript to build/
npm run format              # Prettier formatting

Project Structure

src/
  index.ts            # Entry point
  app.ts              # Express app + MCP transport wiring (per-session map)
  config.ts           # Zod-validated v2 env config (with v1 var detection)
  auth.ts             # Multi-key Bearer middleware + Origin allowlist
  audit.ts            # Audit logger (sha256 caller-key prefix)
  health.ts           # /health endpoint
  server.ts           # MCP server factory (registers tools/resources/prompts)
  resources.ts        # MCP resources
  prompts.ts          # MCP prompts
  format.ts           # Markdown formatting helpers
  client/
    actual-client.ts  # ActualClient interface (boundary)
    fake-client.ts    # In-memory fake for unit tests
    sdk-client.ts     # Production @actual-app/api SDK adapter
    sync-coalescer.ts # 2s debounce for sync calls
    lifecycle.ts      # init/shutdown with p-retry + signal handlers
  tools/
    register.ts       # Aggregator
    shared.ts         # readTool / writeTool wrappers
    {accounts,budget,categories,notes,payees,query,rules,schedules,tags,transactions,utility}.ts
tests/
  unit/               # Vitest + FakeActualClient
  integration/        # Real SDK against committed budget fixture
  e2e/                # docker-compose smoke suite
docker/               # Production + dev compose

Tech Stack

  • Runtime: Node.js 22, TypeScript (strict mode)
  • MCP SDK: @modelcontextprotocol/sdk
  • SDK: @actual-app/api v26 (in-process, not HTTP proxy)
  • Validation: Zod v4
  • Resilience: p-retry (exponential backoff), 2-second sync coalescer
  • Security: helmet, express-rate-limit, multi-key Bearer with constant-time compare, Origin allowlist, audit logger
  • Testing: Vitest (unit + integration + e2e), in-memory fake client, committed budget fixture
  • Linting: ESLint (strictTypeChecked), Prettier
  • CI/CD: GitHub Actions, release-please, Docker multi-arch builds
  • Commits: Conventional Commits (commitlint + husky)

License

MIT © Bernard G. Tapiru, Jr.

Ver o original no GitHub

Bom para

Relacionados