ynab-mcp

Demonstração

_{Cole um recibo → transação dividida em itens em segundos}

O que você pode fazer

Como 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

Recursos

• Itemização de recibos — Cole um recibo e obtenha uma transação dividida em itens com alocação automática de impostos distribuída entre as linhas.
• Conciliação bancária (beta) — Importe um CSV bancário, faça correspondência difusa com o YNAB, detecte transações ausentes ou incompatíveis e aplique correções em massa.
• 35 ferramentas YNAB — Cobertura completa, além de transações programadas e análises periódicas determinísticas.
• Segurança de escrita por padrão — O modo de pré-visualização exige uma confirmação de curta duração e uso único vinculada à solicitação exata validada.
• Perfis de ferramentas menores — Escolha core, read-only ou full na inicialização sem registro dinâmico.
• Sincronização delta — Busca apenas dados alterados desde a última solicitação, mantendo tudo rápido.
• Markdown ou JSON — Todas as ferramentas de leitura suportam response_format: tabelas Markdown legíveis (padrão) ou JSON estruturado.
• Nativo MCP — Saídas estruturadas, anotações, API de conclusões e modelos de recursos.

Como funciona a conciliação

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."

Configuração (2 minutos)

1 — Obtenha um token YNAB

1. Abra o Aplicativo Web YNAB
2. Vá para Configurações da conta → Configurações do desenvolvedor → Novo token
3. Copie-o (exibido apenas uma vez)

2 — Instalação

{
  "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 — Experimente estes 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.

Ferramentas (35)

Configuração

Consulte .env.example para todas as opções.

Modos de gravação e compatibilidade

preview é o padrão conservador. Uma chamada de mutação primeiro executa seu caminho dry_run existente e retorna um token de confirmação. Esse token expira após dois minutos, pode ser usado uma única vez e só autoriza o mesmo nome canônico de ferramenta e argumentos validados. read-only não registra ferramentas de mutação do YNAB. enabled preserva o comportamento de gravação direta pré-segurança para usuários que optam explicitamente por ele.

Os valores de transação agora preferem amount_decimal (por exemplo, -12.34) ou o campo bruto explícito amount_milliunits (-12340). O financiamento de categorias também prefere budgeted_decimal ou budgeted_milliunits. Os campos antigos amount e budgeted continuam aceitos como aliases obsoletos de milliunits para compatibilidade retroativa; seu significado nunca é inferido.

Perfis de ferramentas

Os perfis são selecionados uma vez na inicialização do servidor, para que os clientes recebam uma resposta tools/list estável:

• core mantém leituras comuns, fluxos de segurança de transações, conciliação, divisão de recibos, revisão programada e análises de gastos.
• read-only expõe todas as ferramentas explicitamente anotadas como somente leitura.
• full expõe a superfície completa de 35 ferramentas, sujeita ao modo de gravação selecionado.

Privacidade e confiança

• O processo do servidor é executado localmente e se comunica com o YNAB pela API do YNAB.
• Seu token de acesso pessoal do YNAB é sensível. Armazene-o na configuração secreta do seu cliente MCP e nunca o cole em uma conversa, issue, fixture ou log.
• Os dados financeiros retornados pelas ferramentas e incluídos em uma conversa podem ser processados pelo provedor de IA selecionado no seu cliente MCP. Revise os controles de dados desse provedor antes de compartilhar informações sensíveis.
• As exportações de transações permanecem no disco local em YNAB_EXPORT_PATH (ou no padrão da plataforma). O servidor não envia arquivos exportados para outros lugares.
• Use read-only para nenhuma gravação no YNAB, preview para confirmação exata da solicitação ou enabled apenas quando gravações diretas forem uma escolha intencional de compatibilidade.
• Este projeto independente de código aberto não é afiliado nem endossado pelo YNAB.

Solução de problemas

Para desenvolvedores

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

Arquitetura e orientações para contribuidores: CLAUDE.md

Arquitetura de conciliação: docs/technical/reconciliation-system-architecture.md

Contribuindo

Relatórios de bugs e reproduções de casos extremos de CSV são muito bem-vindos, especialmente para conciliação bancária: Abra uma issue

PRs são bem-vindos — execute npm test e npm run lint antes de enviar.

Licença

AGPL-3.0