Actual Budget

Integra Actual Budget con asistentes LLM para gestionar tus finanzas personales.

Documentación

Servidor MCP de Actual Budget

Servidor MCP para integrar Actual Budget con Claude y otros asistentes LLM.

Descripción general

El Servidor MCP de Actual Budget te permite interactuar con tus datos financieros personales de Actual Budget usando lenguaje natural a través de LLMs. Expone tus cuentas, transacciones y métricas financieras mediante el Protocolo de Contexto de Modelos (MCP).

Características

Recursos

Listados de cuentas - Explora todas tus cuentas con sus saldos
Detalles de cuenta - Consulta información detallada sobre cuentas específicas
Historial de transacciones - Accede a datos de transacciones con detalles completos

Herramientas

Gestión de transacciones y cuentas

get-transactions - Recupera y filtra transacciones por cuenta, fecha, monto, categoría o beneficiario
create-transaction - Crea una nueva transacción en una cuenta con categoría, beneficiario y notas opcionales
update-transaction - Actualiza una transacción existente con nueva categoría, beneficiario, notas o monto
get-accounts - Recupera una lista de todas las cuentas con su saldo actual e ID
balance-history - Consulta los cambios de saldo de cuentas a lo largo del tiempo

Informes y análisis

spending-by-category - Genera desgloses de gastos categorizados por tipo
monthly-summary - Obtén métricas mensuales de ingresos, gastos y ahorros
budget-vs-actual - Compara montos presupuestados contra gastos reales por categoría
net-worth - Realiza seguimiento de activos, pasivos y patrimonio neto en todas las cuentas a lo largo del tiempo
category-trends - Observa cómo se mueve el gasto en cada categoría mes a mes, con dirección de tendencia
spending-by-payee - Clasifica beneficiarios por cuánto se gastó (o recibió) con cada uno
cash-flow - Reporta ingresos, gastos y flujo de caja neto por mes o semana

Las cinco herramientas anteriores devuelven JSON en lugar de markdown, para que los montos permanezcan legibles por máquina. Cada monto es un número entero de centavos, y cada respuesta incluye un campo amountsIn que describe las convenciones de signo que utiliza.

Informes personalizados y paneles

get-custom-reports - Recupera todos los informes personalizados guardados de la sección Informes
create-custom-report - Crea un informe personalizado guardado
update-custom-report - Actualiza campos en un informe personalizado guardado, dejando el resto sin cambios
delete-custom-report - Elimina un informe personalizado guardado
get-dashboards - Recupera cada página de panel y los widgets dispuestos en ella
add-dashboard-widget - Añade un widget a una página de panel
update-dashboard-widget - Actualiza la configuración, posición o tamaño de un widget
remove-dashboard-widget - Elimina un widget de su página
organize-dashboard - Reposiciona y redimensiona varios widgets a la vez
create-dashboard-page / rename-dashboard-page / delete-dashboard-page - Gestiona páginas de panel

Beneficiarios

get-payees - Recupera una lista de todos los beneficiarios con sus detalles
create-payee - Crea un nuevo beneficiario
update-payee - Actualiza los detalles de un beneficiario existente
delete-payee - Elimina un beneficiario

Reglas

get-rules - Recupera una lista de todas las reglas de transacción
create-rule - Crea una nueva regla de transacción con condiciones y acciones
update-rule - Actualiza una regla de transacción existente
delete-rule - Elimina una regla de transacción

Prompts

financial-insights - Genera perspectivas y recomendaciones basadas en tus datos financieros
budget-review - Analiza tu cumplimiento presupuestario y sugiere ajustes

Instalación

Requisitos previos

Node.js (v16 o superior)
Actual Budget instalado y configurado
Claude Desktop u otro cliente compatible con MCP
Docker Desktop (opcional)

Acceso remoto

Extrae la imagen docker más reciente:

docker pull sstefanov/actual-mcp:latest

Configuración local

Clona el repositorio:

git clone https://github.com/s-stefanov/actual-mcp.git
cd actual-mcp

Instala las dependencias:

npm install

Compila el servidor:

npm run build

Compila la imagen docker local (opcional):

docker build -t <local-image-name> .

Configura las variables de entorno (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: contraseña de cifrado de presupuesto separada

Si tu configuración de Actual requiere una contraseña diferente para desbloquear los datos de presupuesto local/cifrado que la contraseña de autenticación del servidor, puedes establecer ACTUAL_BUDGET_ENCRYPTION_PASSWORD además de ACTUAL_PASSWORD.

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

Ciclo de vida de la conexión

El servidor mantiene una conexión compartida de Actual durante toda su vida útil y serializa las operaciones de presupuesto a través de ella. Los datos descargados se resincronizan cuando superan la ventana de frescura de ACTUAL_SYNC_TTL_MS. Tanto en modo stdio como HTTP, SIGINT y SIGTERM drenan el trabajo en curso antes de que el servidor se apague. Actual ya no se inicializa ni se apaga en cada llamada de herramienta.

Semántica de informes

Los saldos e historiales de saldo están limitados hasta hoy; las transacciones con fecha futura se excluyen, y la fila del historial de saldo del mes actual es parcial.
Las cuentas cerradas dentro del presupuesto permanecen incluidas en los informes históricos; las cuentas cerradas fuera del presupuesto permanecen excluidas por defecto.
Los ingresos mensuales siguen los metadatos del grupo de ingresos de Actual. Los reembolsos se compensan con los gastos, los meses sin actividad cuentan en los promedios, y los pares de transferencia sin categorizar se omiten.
El antiguo bucket de Inversiones se elimina de los resúmenes mensuales.

Uso con Claude Desktop

Para usar este servidor con Claude Desktop, añádelo a tu configuración de Claude:

En MacOS:

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

En Windows:

code %APPDATA%\Claude\claude_desktop_config.json

Añade lo siguiente a tu configuración...

a. Usando Node.js (versión 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 (imágenes locales o 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"
      ]
    }
  }
}

Después de guardar la configuración, reinicia Claude Desktop.

💡 ACTUAL_DATA_DIR es opcional si estás usando ACTUAL_SERVER_URL.

💡 Usa --enable-write para habilitar herramientas de acceso de escritura.

Ejecutar un servidor SSE

Para exponer el servidor a través de un puerto 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: Al usar --enable-bearer, la variable de entorno BEARER_TOKEN debe estar configurada.
🔒 Esto es muy recomendable si expones tu servidor a través de una URL pública.

Consultas de ejemplo

Una vez conectado, puedes hacer preguntas a Claude como:

"¿Cuál es mi saldo de cuenta actual?"
"Muéstrame mis gastos por categoría el mes pasado"
"¿Cuánto gasté en comestibles en enero?"
"¿Cuál es mi tasa de ahorro en los últimos 3 meses?"
"¿En qué categorías estoy gastando de más este mes?"
"¿Cómo ha cambiado mi patrimonio neto en el último año?"
"¿Con qué beneficiarios gasto más?"
"¿Mi gasto en comestibles está tendiendo al alza o a la baja?"
"Analiza mi presupuesto y sugiere áreas para mejorar"
"¿Qué informes personalizados tengo?"
"Añade un widget de patrimonio neto a mi panel de Plan de Gastos"
"Reorganiza mi panel para que la tarjeta de flujo de caja esté a ancho completo en la parte superior"

Uso con Codex CLI

Ejemplo de configuración de Codex:

En ~/.codex/config.toml:

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

Apunta Codex al mismo puerto que pasas a npm start -- --sse --port <PORT>.

Desarrollo

Para desarrollo con reconstrucción automática:

npm run watch

Probando la conexión con Actual

Para verificar que el servidor puede conectarse a tus datos de Actual Budget:

node build/index.js --test-resources

Depuración

Dado que los servidores MCP se comunican a través de stdio, la depuración puede ser desafiante. Puedes usar el Inspector MCP:

npx @modelcontextprotocol/inspector node build/index.js

Puerta de validación E2E

El conjunto de pruebas de extremo a extremo (vitest.e2e.config.ts) inicia un servidor real de Actual Budget en un contenedor Docker (a través de Testcontainers), siembra un presupuesto, y lo impulsa a través de un cliente MCP real sobre stdio para verificar que cuentas, transacciones, categorías, beneficiarios, reglas e importaciones realmente persisten. Requiere que Docker esté ejecutándose localmente.

En CI, el trabajo e2e-test en .github/workflows/pr-validation.yml solo se ejecuta en PRs de release-please (prefijo de rama release-please--) o cuando a un PR se le asigna la etiqueta run-e2e — no se ejecuta en cada PR por defecto, ya que necesita Docker y tarda más que las verificaciones estándar.

Para ejecutarlo localmente:

npm run build && npm run test:e2e

Docker debe estar instalado y ejecutándose; el conjunto de pruebas extrae e inicia la imagen del servidor de Actual automáticamente.

Estructura del proyecto

index.ts - Implementación principal del servidor
types.ts - Definiciones de tipos para respuestas de API y parámetros
prompts.ts - Plantillas de prompts para interacciones con LLM
utils.ts - Funciones auxiliares para formato de fechas y más

Registro y descubrimiento

actual-mcp se publica en el Registro MCP oficial como io.github.s-stefanov/actual-mcp. Los metadatos del registro residen en server.json y se publican automáticamente en cada lanzamiento (ver .github/workflows/release-please.yml).

Anuncia dos transportes en el paquete npm — stdio (predeterminado) y streamable-http (a través de la bandera --sse). (También se publica una imagen Docker, pero aún no está listada como paquete de registro.)

Los listados de directorio posteriores al lanzamiento se rastrean en docs/mcp-registry-checklist.md.

Licencia

MIT

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Solicitud de Extracción.