convez.ai
MCP ServerFinanceiroIntermediário
xkel

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 GitHub
InicialPluginScore · de 0 a 100

Servidor 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-server

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
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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

Setup

  1. Install dependencies:
bundle install
  1. 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.

  1. 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)

  1. Start the Rails server: bin/rails server -p 3000
  2. In another terminal: ngrok http 3000
  3. Copy the HTTPS URL from ngrok (e.g. https://abc123.ngrok.app)
  4. 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
  5. 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_TOKEN behind 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_TOKEN to require a bearer token on /mcp; clients send it as Authorization: Bearer <token>
  • YNAB API rate limit: 200 requests per hour
Ver o original no GitHub

Bom para

Relacionados