YNAB MCP Server for Secure Financial Data

Overview

This MCP (Model Context Protocol) server provides a secure bridge between YNAB (You Need A Budget) and AI assistants or agent frameworks. The server exposes a small set of controlled endpoints that let models retrieve budget, account, category, and transaction data from a YNAB account without giving the model direct access to your long‑lived YNAB credentials or the full API. It is intended to limit exposure of sensitive financial data while enabling context‑aware AI interactions (for example, generating summaries, answering questions about recent spending, or creating suggested transactions).

Running the MCP server locally or in a trusted environment keeps your financial data under your control. The server can filter, redact, and rate‑limit responses and can be configured with granular access rules so an AI assistant only receives exactly the data it needs for a specific task.

Features

• Lightweight MCP server that proxies and filters YNAB API responses
• OAuth / token configuration for secure access to a YNAB account
• Granular tool endpoints (budgets, accounts, categories, transactions)
• Response redaction and field-level filtering to protect PII
• Optional caching to reduce API calls and speed responses
• Rate limiting and basic audit logging of tool calls
• Docker and native run options for local or hosted deployment
• Simple JSON RPC / HTTP endpoints compatible with agent frameworks

Installation / Configuration

Clone the repository and install dependencies (example assumes a Node.js based server):

git clone https://github.com/ChuckBryan/ynabmcpserver.git
cd ynabmcpserver
npm install

Create a .env file with required settings (example):

YNAB_ACCESS_TOKEN=your_ynab_personal_access_token
MCP_SERVER_PORT=3000
MCP_ALLOWED_ORIGINS=http://localhost:3001
CACHE_TTL_SECONDS=60
RATE_LIMIT_PER_MINUTE=60
LOG_LEVEL=info

Run locally:

npm start
# or, if the repo provides a script:
node server.js

Run with Docker:

docker build -t ynab-mcp-server .
docker run -d \
  -p 3000:3000 \
  -e YNAB_ACCESS_TOKEN=your_ynab_token \
  -e MCP_SERVER_PORT=3000 \
  --name ynab-mcp-server \
  ynab-mcp-server

Example systemd unit (for a Linux host):

[Unit]
Description=YNAB MCP Server
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/ynabmcpserver
ExecStart=/usr/bin/node server.js
EnvironmentFile=/opt/ynabmcpserver/.env
Restart=on-failure

[Install]
WantedBy=multi-user.target

Important security notes:

• Use short‑lived or limited-scope tokens where possible.
• Run the server in a trusted environment (local machine or private cloud).
• Enable TLS when exposing the service beyond localhost.

Available Tools

The server exposes a set of curated tools/endpoints that an assistant or agent can call. Below is a representative table of available resources.

Example tool call (curl):

curl "http://localhost:3000/mcp/transactions?budget_id=abcd-ef&since_date=2026-01-01"

Tool responses are JSON and the server may redact or omit sensitive fields (account numbers, full payee addresses) according to configuration.

Use Cases

• Summarize spending by category for the past month so an assistant can create a natural‑language recap.

  • Agent flow: call /mcp/transactions?since_date=2026-03-01 → aggregate by category → present summary to user.

• Generate a suggested budget change based on recurring overspending.

  • Agent flow: retrieve categories and recent transactions → detect recurring overspend → return recommendation.

• Detect anomalous or duplicate transactions for simple fraud detection.

  • Agent flow: query recent transactions over a threshold → run duplication/similarity logic locally → flag candidates.

• Assistants that compose actions safely:

  • Read‑only agents can query transactions and budgets without being allowed to create or modify transactions.
  • When write capability is needed, require explicit user confirmation and enforce server‑side ACL checks before calling create endpoints.

Additional Notes

• The MCP server is designed to be an integration piece; it does not replace YNAB’s API but acts as a controlled gateway.
• Configure logging and retention according to your privacy needs; avoid storing raw transaction payloads unless necessary.
• Combine this server with local LLMs or remote model APIs: expose only the minimal toolset and data the model needs to accomplish a task.

For developers new to the project, start by running the server locally, inspecting the JSON responses from the endpoints, and adding or tightening filters for any fields you consider sensitive before exposing the server to an assistant or third‑party service.