convez.ai
MCP ServerFinanceiroIntermediário
redlinelabs-dev

YNAB MCP Server

redlinelabs-dev/ynab-mcp

Conecte seu YNAB ao Claude para gerenciar finanças pessoais

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que integra YNAB (You Need A Budget) com Claude, fornecendo ferramentas para gerenciar orçamentos, contas, categorias e transações. Permite leitura de dados financeiros e edições direcionadas como criar transações e ajustar valores orçamentários.

Instalação

$npx convez-ai redlinelabs-dev/ynab-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
0
Forks
1
Acompanhando
0
Saúde
50%
Último commit
há 1 mês
Versão
ynab-mcp-v0.2.2
Issues abertas
2
Contribuidores
1

Casos de uso

  • Consultar saldos e categorias de orçamento em tempo real
  • Criar e atualizar transações manualmente sem acessar a app
  • Categorizar e aprovar múltiplas transações em lote
  • Analisar gastos e gerar relatórios de despesas por categoria
  • Identificar transações duplicadas automaticamente

Veredito

Integração sólida e bem-estruturada para quem usa YNAB e quer automatizar gestão financeira via Claude. Cobre fluxos essenciais (leitura, criação, categorização), embora dependa de ligação manual de contas bancárias — limitação do próprio YNAB API.

README

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

@redlinelabs/ynab-mcp

MCP server for YNAB (You Need A Budget). Gives AI assistants (Claude Desktop, Claude Code, etc.) tools to browse budgets, accounts, categories, transactions, and months, and to make targeted edits (set a category's budgeted amount, create/update transactions).

All monetary amounts in YNAB are milliunits — 1000 = one currency unit. Read tools return both the raw milliunit value and a human-friendly *_units sibling; write tools take milliunits.

Bank linking is not possible via the YNAB API — it's a YNAB web/app-only feature. This server creates only manual accounts; once you've linked a bank in the app, import_transactions can pull its latest activity. The API rate limit is 200 requests/hour per token.

Tools

Tools are organized into toolsets (groups) you can enable/disable — see Toolsets. ✏️ marks mutating (write) tools, which can be disabled all at once with YNAB_READ_ONLY.

budgets

ToolDescription
list_budgetsAll budgets on the account
budget_settingsCurrency + date-format settings for a budget

accounts

ToolDescription
list_accountsAccounts in a budget, with balances
get_accountOne account by id
create_account ✏️Create a manual account (API can't bank-link — see below)

categories

ToolDescription
list_categoriesCategory groups and their categories
get_categoryOne category by id
update_category_budget ✏️Set the budgeted amount (milliunits) for a month

transactions

ToolDescription
list_transactionsTransactions (filter by account/date/uncategorized/unapproved)
get_transactionOne transaction by id
create_transaction ✏️Create a transaction
update_transaction ✏️Update fields on an existing transaction
bulk_update_transactions ✏️Categorize and/or approve many transactions in one call
delete_transaction ✏️Delete a transaction (e.g. a confirmed duplicate)
find_duplicate_transactionsFind duplicate clusters (same account+amount+date) for review
import_transactions ✏️Pull latest activity on already bank-linked accounts
spending_summaryAggregate spend by category/payee over a date range
payee_transactionsTransaction history for one payee
category_transactionsTransaction history for one category

scheduled

ToolDescription
list_scheduled_transactionsRecurring/upcoming transactions with next due

months

ToolDescription
list_monthsBudget months with income/budgeted/activity summary
get_monthOne month (default current) with category detail

payees

ToolDescription
list_payeesPayees in a budget

Setup

1. Create a YNAB Personal Access Token

In YNAB, go to Account Settings → Developer Settings → New Token.

2. Configure environment

Create a .env file (or pass env vars directly):

YNAB_TOKEN=your-personal-access-token
YNAB_BUDGET_ID=last-used
  • YNAB_TOKEN — your Personal Access Token (required)
  • YNAB_BUDGET_ID — default budget for tools that omit budget_id. Accepts a budget UUID or an alias (last-used, default). Defaults to last-used.
  • YNAB_TOOLSETS — optional comma-separated toolsets to expose (default: all)
  • YNAB_READ_ONLY — optional; set to true to expose only read tools

3. Add to Claude Code

claude mcp add --transport stdio \
  --env YNAB_TOKEN=your-personal-access-token \
  --env YNAB_BUDGET_ID=last-used \
  ynab -- npx -y @redlinelabs/ynab-mcp

Env vars are scoped to the server process — no global environment setup needed.

4. Add to Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "ynab": {
      "command": "npx",
      "args": ["-y", "@redlinelabs/ynab-mcp"],
      "env": {
        "YNAB_TOKEN": "your-personal-access-token",
        "YNAB_BUDGET_ID": "last-used"
      }
    }
  }
}

Toolsets

To avoid bloating the model's context window, you can expose only the tool groups you need. Two independent controls:

  • YNAB_TOOLSETS — comma-separated group names, or all (default). Groups: budgets, accounts, categories, transactions, months, payees, scheduled.
  • YNAB_READ_ONLY — true/1 exposes only non-mutating tools (drops every ✏️ tool).
# Only read budgets, accounts, and transactions — never write:
YNAB_TOOLSETS=budgets,accounts,transactions
YNAB_READ_ONLY=true

Disabled tools are hidden from tools/list and rejected if called directly.

Development

npm install
npm run dev        # watch mode
npm test           # run the Vitest suite
npm run check      # typecheck + lint + format check + tests
npm run build      # production build

Tests are unit/integration style against the public module interfaces, using an injected fake fetch — they never touch the live YNAB API or the rate limit.

Versioning

This project uses 0ver (zero-based versioning). The major version will remain at 0 indefinitely. Breaking changes bump the minor version; features and fixes bump the patch version.

Releases are automated via release-please. Commits must follow Conventional Commits.

Ver o original no GitHub

Bom para

Relacionados