YNAB MCP Server
xkel/ynab-mcp-server
Integre o YNAB em Claude e ChatGPT via MCP com controle total do seu orçamento
Ver no GitHubServidor MCP em Ruby/Rails que expõe toda a API do YNAB como ferramentas para Claude, ChatGPT e outros clientes MCP. Permite integrar seu orçamento do YNAB diretamente em aplicações de IA, com autenticação segura via bearer token.
Instalação
npx convez-ai xkel/ynab-mcp-server1 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 via conversas com IA
- Automatizar registros de transações através de prompts em linguagem natural
- Analisar gastos e tendências financeiras com assistentes de IA
Veredito

Solução robusta para quem quer integrar YNAB em fluxos de IA. Requer setup técnico (Ruby, variáveis de ambiente, auth token) e clareza sobre que dados expõe — ideal para desenvolvedores que entendem o trade-off entre conveniência e segurança de um token estático.
README
A tradução para o português deste README ainda está na fila.
YNAB MCP Server
A Ruby/Rails MCP (Model Context Protocol) server that exposes the full YNAB API as tools for Claude and ChatGPT.
Prerequisites
- Ruby >= 3.3
- A YNAB account
- A YNAB Personal Access Token (get one here)
Setup
- Install dependencies:
bundle install
- Configure your YNAB token (and an auth token):
cp .env.example .env
# Edit .env and add your YNAB Personal Access Token
Set MCP_AUTH_TOKEN to a random secret to require a bearer token on every
request to /mcp (recommended for anything beyond localhost):
openssl rand -hex 32 # paste the result as MCP_AUTH_TOKEN in .env
If MCP_AUTH_TOKEN is left blank the endpoint is unauthenticated — fine for
local development on localhost, but never expose an unauthenticated URL
publicly, since the server holds your YNAB token and anyone who reaches it can
read and write your budget.
- Start the server:
bin/rails server -p 3000
The MCP endpoint is available at POST http://localhost:3000/mcp.
Connecting to ChatGPT
Local Development (with ngrok)
- Start the Rails server:
bin/rails server -p 3000 - In another terminal:
ngrok http 3000 - Copy the HTTPS URL from ngrok (e.g.
https://abc123.ngrok.app) - In ChatGPT:
- Open Settings > enable Developer Mode
- Go to the Connectors tab
- Click Add connector and enter your ngrok URL +
/mcp - Example:
https://abc123.ngrok.app/mcp
- Start a new chat, click Add sources, and select your YNAB connector
Production Deployment
Deploy to any Ruby-friendly host (Fly.io, Render, Heroku, etc.):
# Example with Fly.io
fly launch
fly secrets set YNAB_API_TOKEN=your_token_here
fly secrets set MCP_AUTH_TOKEN=$(openssl rand -hex 32)
fly deploy
Then add the production URL (https://<your-app>/mcp) as a connector. Keep the
MCP_AUTH_TOKEN value handy — clients must send it as a bearer token.
Connecting to Claude
This server speaks Streamable HTTP at POST /mcp and returns plain
application/json responses, which is what Claude's MCP clients expect. The
endpoint is protected by a static bearer token (MCP_AUTH_TOKEN), so how you
connect depends on which Claude client you use — pick one of the three paths
below.
Note: A static bearer token is not OAuth. The claude.ai web Connectors UI does not provide a field for custom headers, so it can only connect to servers that use OAuth or no auth. To use this server's bearer token from Claude, use the API or Claude Desktop paths below. (See OAuth if you specifically need the web UI.)
Path 1 — Claude API (MCP connector)
Pass the URL and bearer token directly via the API's MCP connector:
{
"model": "claude-opus-4-8",
"mcp_servers": [
{
"type": "url",
"url": "https://your-app.fly.dev/mcp",
"name": "ynab",
"authorization_token": "YOUR_MCP_AUTH_TOKEN"
}
],
"messages": [{ "role": "user", "content": "Show me my budgets" }]
}
Requests need the anthropic-beta: mcp-client-2025-04-04 header. The
authorization_token is sent to the server as Authorization: Bearer ....
Path 2 — Claude Desktop (via mcp-remote)
Claude Desktop connects to local (stdio) servers, so bridge to this remote
server with mcp-remote, passing the
bearer token as a header. Edit claude_desktop_config.json
(Settings → Developer → Edit Config):
{
"mcpServers": {
"ynab": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://your-app.fly.dev/mcp",
"--header",
"Authorization: Bearer YOUR_MCP_AUTH_TOKEN"
]
}
}
}
Restart Claude Desktop; the YNAB tools appear in the tools menu. For local
development point the URL at your ngrok tunnel (https://abc123.ngrok.app/mcp).
Path 3 — claude.ai web (Connectors UI)
Pro/Max/Team/Enterprise plans can add a remote server under Settings →
Connectors → Add custom connector with the URL https://your-app.fly.dev/mcp.
The web UI has no field for a bearer token, so this path works only if the server is reachable without one. Two options:
- Run without
MCP_AUTH_TOKENbehind a hard-to-guess URL (weaker; the URL becomes the only secret), or - Add OAuth to the server (see below) so the UI can authenticate properly.
OAuth
The web Connectors UI authenticates remote servers via OAuth 2.0 (it performs
authorization-server metadata discovery and a standard auth-code flow). The
underlying mcp gem does not ship an OAuth layer, so supporting this path means
adding one to the Rails app. It is not implemented here yet — use Path 1 or 2 if
you need authenticated access today.
Available Tools (18)
Budgets
- list_budgets - List all your YNAB budgets (use this first!)
- get_budget - Get summary info for a specific budget
Accounts
- list_accounts - List all accounts with balances
- get_account - Get details for a single account
Categories
- list_categories - List all categories grouped by group
- get_category - Get details for a single category
- update_month_category - Assign money to a category for a specific month
Transactions
- list_transactions - List transactions with optional filters (account, category, month, type, date)
- get_transaction - Get full details for a single transaction
- create_transaction - Create a new transaction
- update_transaction - Update/approve an existing transaction
- delete_transaction - Delete a transaction
Payees & Months
- list_payees - List all payees
- list_budget_months - List budget months with income/spending summaries
- get_budget_month - Get detailed breakdown for a specific month
Scheduled Transactions
- list_scheduled_transactions - List recurring transactions
- create_scheduled_transaction - Create a new recurring transaction
- update_scheduled_transaction - Update a recurring transaction
Example Prompts
Once connected to ChatGPT, try:
- "Show me my budgets"
- "What's my checking account balance?"
- "How much have I spent on groceries this month?"
- "Add a $45.99 transaction at Target on my Chase card"
- "Show me all unapproved transactions"
- "How much money do I have left to budget this month?"
- "What are my upcoming recurring bills?"
Notes
- All monetary amounts use dollars (e.g. $45.99), not YNAB milliunits
- Your YNAB token is stored as an environment variable and never sent to the AI client
- Set
MCP_AUTH_TOKENto require a bearer token on/mcp; clients send it asAuthorization: Bearer <token> - YNAB API rate limit: 200 requests per hour