YNAB Model Context Protocol Gateway

This document details the deployment and functionality of the Dockerized MCP (Model Context Protocol) server engineered to bridge conversational AI models (like Claude) with the You Need A Budget (YNAB) financial ecosystem. It mandates secure OAuth handshake for all data access.

System Capabilities & Status

This toolset offers robust capability across several domains:

• Secure, OAuth-backed connectivity to the YNAB API.
• Comprehensive management functions for budgetary structures and individual accounts.
• Facilitation of new transaction recording and automatic assignment to proper cost centers.
• Advanced resource allocation features, including AI-informed suggested distributions.
• Support for managing disparate budget instances (e.g., personal vs. shared family funds).
• Built-in mitigation strategies for YNAB API rate constraints (max 200 calls/hour).
• Performance enhancement via data caching mechanisms.

Advanced Fund Allocation Features

Significant recent enhancements focus on category control:

• Bulk Category Funding: Execute the movement of 'Ready to Assign' funds across multiple target categories simultaneously.
• Predictive Allocations: Leverage machine learning insights to propose optimized budget splits based on historical spending habits and defined financial targets.

Refer to the docs/category-management.md document for exhaustive feature specifications.

Deployment Guide

Prerequisites for Operation

• A functional installation of Docker.
• Node.js environment, version 18 or higher (recommended for auxiliary development).
• The Claude Code Command Line Interface (CLI).
• An active YNAB subscription and associated API credentials.

Setup Procedure

1. Obtain a local copy of the source repository.
2. Duplicate the template configuration file (config/config.example.js) to the active configuration file (config/config.js), populating it with your required YNAB access keys.
3. Construct the execution image: docker build -t ynab-mcp:latest .
4. Prepare the execution manifest for the AI agent (Claude): json { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "/path/to/data:/app/data", "-v", "/path/to/config:/app/config", "-e", "NODE_ENV=production", "ynab-mcp:latest" ] }
5. Register this service definition with the AI orchestrator: bash claude mcp add-json ynab '{"command": "docker", "args": ["run", "--rm", "-i", "-v", "/path/to/data:/app/data", "-v", "/path/to/config:/app/config", "-e", "NODE_ENV=production", "ynab-mcp:latest"]}' Alternatively, utilize a saved configuration file: bash claude mcp add-json ynab "$(cat config.json)"
6. The system will initiate the OAuth sequence, requiring user authorization with the YNAB service upon first interaction.

Operational Caveats (Identified Limitations)

We are currently resolving several known deficiencies:

1. Transaction Retrieval Flaw: The list_transactions utility returns erroneous "invalid date" exceptions when the sinceDate parameter is employed.
2. Tool Exposure Discrepancy: Certain functionalities defined internally within the code base are not currently exposed or callable via the MCP interface.
3. Environment Instability: Tools exhibit functional discrepancies, operating correctly during isolated testing (using test-mcp.js) but failing upon deployment within the live MCP service context.

Remediation Efforts Underway

Active development branches target these problems:

• Resolution of date parsing issues in transaction retrieval is targeted on the fix-transactions-api branch.
• Ensuring comprehensive registration and availability of all defined API functions is being addressed via the fix-mcp-registration branch.

System Underpinnings & Trust

• Security Posture: Access credentials (tokens) are persisted securely within a designated, mounted Docker volume.
• Data Privacy: Sensitive operational data is explicitly excluded from system logging outputs.
• Authentication Standard: Adherence to OAuth 2.0 specifications for identity verification.
• Access Control: Capability to enforce read-only operational modes.

Technical Stack

This implementation adheres strictly to the MCP specification, leveraging:

• Language/Runtime: Node.js paired with the official MCP Software Development Kit (SDK).
• Deployment Method: Containerization via Docker for isolated execution.
• API Interfacing: Utilization of the official YNAB JavaScript SDK for all remote service calls.
• Security Framework: Implementation based on OAuth 2.0 principles.

Acknowledgements

We recognize the foundational technologies utilized:

• The official YNAB API specification.
• The open-source YNAB JavaScript Library.
• The computational platform, Anthropic Claude.