YNAB Model Context Protocol Gateway

This entry defines a service layer implementing the Model Context Protocol (MCP) for secure interaction with the You Need A Budget (YNAB) financial application programming interface (API).

Capabilities Overview

• Access budgetary structures, asset registries, and account classifications.
• Perform CRUD operations on financial transactions (fetch, introduce, revise).
• Provision new asset classifications within budgetary frameworks.
• Modify assigned funding levels for designated asset classifications on a monthly basis.
• Generate consolidated reports summarizing budgetary health.

Pre-requisites for Operation

• Runtime environment: Python version 3.13 or newer is mandated.
• Authentication Credential: A valid YNAB service access key (obtainable via Developer Settings Link).
• Dependency Manager: Utilization of the UV package manager is suggested for optimized dependency resolution.

Setup Instructions

1. Obtain a local copy of the source repository: bash git clone https://github.com/ntdef/ynab-mcp.git cd ynab-mcp

2. Establish an isolated runtime environment: bash uv venv

3. Activate the isolated environment:

   • Windows OS: bash venv\Scripts\activate

   • Unix/macOS OS: bash source venv/bin/activate

4. Install required packages using UV: bash # Installation of uv itself is optional: python -m pip install uv uv sync

5. Configure environment variables: Duplicate .env.example into .env and insert your personal YNAB API credential. bash cp .env.example .env # Please edit the .env file to input your secret key.

Execution Guide

Initiating the Service Endpoint

bash uv run ynab-mcp

The service initializes in standard input/output communication mode, resulting in no visible console feedback upon success.

Exposed Interface Methods

The YNAB MCP Gateway exposes the following functional calls:

Budgetary Structure Operations

• get_budgets: Fetches all organizational budgets linked to the authenticated user profile.
• get_budget_summary: Retrieves a consolidated overview of a specific budget, optionally scoped to a particular calendar month.

Account Registry Operations

• get_accounts: Fetches all associated financial accounts for a designated budget structure.

Classification Operations

• get_categories: Retrieves the full hierarchy of classifications for a specified budget.
• create_category: Introduces a novel classification within a designated budgetary grouping.
• update_category_budgeted: Revises the allocated funding amount for a specific classification within a defined monthly period.

Transaction Record Operations

• get_transactions: Queries transactional records for a budget, supporting optional filtering by date range, specific account, or classification.
• create_transaction: Records a new financial entry into the specified budget.
• update_transaction: Modifies one or more attributes of an existing transactional record.

Development Lifecycle

Running Automated Checks

bash uv run pytest

Code Formatting Standards

This repository adheres to formatting enforced by Black and isort. To apply automatic code standardization:

bash uv run isort src tests uv run black src tests

Legal Statement

Distributed under the terms of the MIT License.

Credits and References

• Portions of the source code benefited from assistance provided by aider.
• Reference: Official YNAB API Specification
• Architectural Inspiration: fastmcp framework developed by Anthropic.