ynab-mcp

Demo

_{Pega un recibo → transacción dividida detallada en segundos}

Lo que puedes hacer

Cómo funciona

graph LR
    U(You) -->|Plain English| C[Claude Desktop<br/>or any MCP client]
    C -->|MCP protocol| S[YNAB MCP Server<br/>35 tools]
    S -->|YNAB API| Y[(Your Budget)]

    style S fill:#2563EB,color:#fff,stroke:#1d4ed8
    style Y fill:#16a34a,color:#fff,stroke:#15803d
    style C fill:#7c3aed,color:#fff,stroke:#6d28d9

Características

• Detalle de recibos — Pega un recibo y obtén una transacción dividida detallada con la asignación de impuestos distribuida automáticamente entre las partidas.
• Conciliación bancaria (beta) — Importa un CSV bancario, haz coincidencias aproximadas con YNAB, detecta transacciones faltantes o no coincidentes y aplica correcciones masivas.
• 35 herramientas de YNAB — Cobertura completa más transacciones programadas y análisis de períodos deterministas.
• Seguridad de escritura por defecto — El modo de vista previa requiere una confirmación de un solo uso y corta duración vinculada a la solicitud validada exacta.
• Perfiles de herramientas más pequeños — Elige core, read-only o full al inicio sin registro dinámico.
• Sincronización delta — Obtiene solo los datos modificados desde la última solicitud, manteniendo la velocidad.
• Markdown o JSON — Todas las herramientas de lectura admiten response_format: tablas markdown legibles (predeterminado) o JSON estructurado.
• Nativo de MCP — Salidas estructuradas, anotaciones, API de completados y plantillas de recursos.

Cómo funciona la conciliación

sequenceDiagram
    participant You
    participant Claude
    participant MCP as YNAB MCP Server
    participant YNAB

    You->>Claude: "Reconcile my checking<br/>with this CSV"
    Claude->>MCP: reconcile_account(csv_data)
    MCP->>YNAB: Fetch transactions
    YNAB-->>MCP: YNAB transactions
    MCP->>MCP: Parse CSV<br/>Fuzzy-match payees & dates<br/>Detect missing / mismatched
    MCP-->>Claude: Matches + recommendations
    Claude->>You: "Found 47 matches, 3 missing.<br/>Apply changes?"
    You->>Claude: "Yes"
    Claude->>MCP: Apply recommended changes
    MCP->>YNAB: Create / update transactions
    MCP-->>Claude: Done
    Claude->>You: "3 transactions created,<br/>account reconciled."

Configuración (2 minutos)

1 — Obtén un token de YNAB

1. Abre YNAB Web App
2. Ve a Configuración de cuenta → Configuración de desarrollador → Nuevo token
3. Cópialo (se muestra solo una vez)

2 — Instalar

{
  "mcpServers": {
    "ynab": {
      "command": "npx",
      "args": ["-y", "@dizzlkheinz/ynab-mcpb@latest"],
      "env": {
        "YNAB_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

{
  "mcpServers": {
    "ynab": {
      "command": "npx",
      "args": ["-y", "@dizzlkheinz/ynab-mcpb@latest"],
      "env": {
        "YNAB_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

[mcp_servers.ynab-mcpb]
command = "npx"
args = ["-y", "@dizzlkheinz/ynab-mcpb@latest"]
env = {"YNAB_ACCESS_TOKEN" = "your-token-here"}
startup_timeout_sec = 120

3 — Prueba estos prompts

List my budgets and set the default to my main budget.
Show recent transactions in my checking account.
How much did I spend on groceries in the last 30 days?
Create a transaction: $42.18 at Trader Joe's yesterday.

Herramientas (35)

Configuración

Consulta .env.example para todas las opciones.

Modos de escritura y compatibilidad

preview es el valor predeterminado conservador. Una llamada de mutación primero ejecuta su ruta dry_run existente y devuelve un token de confirmación. Ese token caduca después de dos minutos, puede usarse una sola vez y solo autoriza el mismo nombre de herramienta canónico y los argumentos validados. read-only no registra herramientas de mutación de YNAB. enabled conserva el comportamiento de escritura directa previo a la seguridad para usuarios que optan explícitamente.

Los montos de transacciones ahora prefieren amount_decimal (por ejemplo, -12.34) o el campo bruto explícito amount_milliunits (-12340). La financiación de categorías prefiere de manera similar budgeted_decimal o budgeted_milliunits. Los campos antiguos amount y budgeted siguen aceptándose como alias de milliunidades obsoletos por compatibilidad con versiones anteriores; su significado nunca se adivina.

Perfiles de herramientas

Los perfiles se seleccionan una vez al iniciar el servidor, por lo que los clientes reciben una respuesta tools/list estable:

• core mantiene lecturas comunes, flujos de seguridad de transacciones, conciliación, división de recibos, revisión programada y análisis de gastos.
• read-only expone cada herramienta explícitamente anotada como solo lectura.
• full expone la superficie completa de 35 herramientas, sujeta al modo de escritura seleccionado.

Privacidad y confianza

• El proceso del servidor se ejecuta localmente y se comunica con YNAB a través de la API de YNAB.
• Tu token de acceso personal de YNAB es sensible. Guárdalo en la configuración secreta de tu cliente MCP y nunca lo pegues en una conversación, issue, fixture o registro.
• Los datos financieros devueltos por las herramientas e incluidos en una conversación pueden ser procesados por el proveedor de IA seleccionado en tu cliente MCP. Revisa los controles de datos de ese proveedor antes de compartir detalles sensibles.
• Las exportaciones de transacciones permanecen en el disco local en YNAB_EXPORT_PATH (o el valor predeterminado de la plataforma). El servidor no sube archivos exportados a ningún otro lugar.
• Usa read-only para no realizar escrituras en YNAB, preview para confirmación exacta de solicitudes, o enabled solo cuando las escrituras directas sean una elección de compatibilidad intencional.
• Este proyecto independiente de código abierto no está afiliado ni respaldado por YNAB.

Solución de problemas

Para desarrolladores

git clone https://github.com/dizzlkheinz/ynab-mcpb.git
cd ynab-mcpb
npm install
cp .env.example .env   # add YNAB_ACCESS_TOKEN
npm run build
npm test

Arquitectura y guía para colaboradores: CLAUDE.md

Arquitectura de conciliación: docs/technical/reconciliation-system-architecture.md

Contribuciones

Los informes de errores y reproducciones de casos límite con CSV son muy bienvenidos, especialmente para la conciliación bancaria: Abre un issue

PRs bienvenidos — ejecuta npm test y npm run lint antes de enviarlos.

Licencia

AGPL-3.0