YNAB MCP Server
redlinelabs-dev/ynab-mcp
Conecte seu YNAB ao Claude para gerenciar finanças pessoais
Ver no GitHubServidor 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-mcp1 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
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*_unitssibling; 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_transactionscan 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
| Tool | Description |
|---|---|
list_budgets | All budgets on the account |
budget_settings | Currency + date-format settings for a budget |
accounts
| Tool | Description |
|---|---|
list_accounts | Accounts in a budget, with balances |
get_account | One account by id |
create_account ✏️ | Create a manual account (API can't bank-link — see below) |
categories
| Tool | Description |
|---|---|
list_categories | Category groups and their categories |
get_category | One category by id |
update_category_budget ✏️ | Set the budgeted amount (milliunits) for a month |
transactions
| Tool | Description |
|---|---|
list_transactions | Transactions (filter by account/date/uncategorized/unapproved) |
get_transaction | One 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_transactions | Find duplicate clusters (same account+amount+date) for review |
import_transactions ✏️ | Pull latest activity on already bank-linked accounts |
spending_summary | Aggregate spend by category/payee over a date range |
payee_transactions | Transaction history for one payee |
category_transactions | Transaction history for one category |
scheduled
| Tool | Description |
|---|---|
list_scheduled_transactions | Recurring/upcoming transactions with next due |
months
| Tool | Description |
|---|---|
list_months | Budget months with income/budgeted/activity summary |
get_month | One month (default current) with category detail |
payees
| Tool | Description |
|---|---|
list_payees | Payees 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 omitbudget_id. Accepts a budget UUID or an alias (last-used,default). Defaults tolast-used.YNAB_TOOLSETS— optional comma-separated toolsets to expose (default: all)YNAB_READ_ONLY— optional; set totrueto 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, orall(default). Groups:budgets,accounts,categories,transactions,months,payees,scheduled.YNAB_READ_ONLY—true/1exposes 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.