YNAB MCP Service Endpoint

A Model Context Protocol (MCP) service implementation designed to interface directly with the YNAB (You Need A Budget) platform via its established Application Programming Interface (API).

Core Capabilities

• Retrieve budget structures, associated accounts, and spending categories.
• Fetch, instantiate (create), and modify transaction records.
• Provision new category structures.
• Adjust allocated funding levels for budgetary categories.
• Obtain aggregated summaries of budget performance.

Prerequisites for Operation

• A runtime environment based on Python version 3.13 or newer.
• Valid credentials for the YNAB service, specifically an API access token (Acquire Token Here).
• The UV package manager (optional, but strongly suggested for efficiency).

Setup Procedure

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

2. Establish an isolated Python virtual environment: bash uv venv

3. Activate the environment:

4. For Windows systems: bash venv\Scripts\activate

5. For Unix/MacOS systems: bash source venv/bin/activate

6. Install required software packages using UV: bash # Installation of uv itself (if not present): # python -m pip install uv uv sync

7. Configure credentials by duplicating the example file and populating the token: bash cp .env.example .env # Open .env to input your secret YNAB API key

Execution

Initiating the Service

uv run ynab-mcp

The service initializes and operates in a standard input/output (stdio) communication mode, typically suppressing console output during normal operation.

Exposed Functionalities (Tools)

The YNAB MCP Service exposes the following distinct operations:

Budget Overview Tools

• get_budgets: Fetches the complete list of financial plans accessible to the authenticated user.
• get_budget_summary: Retrieves a performance overview for a budget, optionally scoped to a specific calendar month.

Account Structure Tools

• get_accounts: Returns a catalog of all financial accounts associated with a specified budget plan.

Category Configuration Tools

• get_categories: Retrieves the complete hierarchy and details of spending categories for a given budget.
• create_category: Provisions a new spending category within a designated budget grouping.
• update_category_budgeted: Modifies the targeted allocation amount for a category within a specified reporting period.

Transaction Ledger Tools

• get_transactions: Fetches entries from the transaction log for a budget, supporting optional filtering by date range, account, or category.
• create_transaction: Records a new financial movement within the specified budget structure.
• update_transaction: Modifies one or more attributes of an existing transaction record.

Development Workflow

Running Verification Suites

uv run pytest

Enforcing Code Style

This codebase adheres to formatting standards enforced by Black and isort. Apply formatting using these commands:

uv run isort src tests
uv run black src tests

Licensing Information

Licensed under the MIT License.

Credits and References

• Portions of this implementation benefited from interaction with aider.
• Official YNAB API Reference.
• Inspired by the fastmcp framework from Anthropic.

WIKIPEDIA: XMLHttpRequest (XHR) is an API presented as a JavaScript object, providing methods to dispatch Hypertext Transfer Protocol (HTTP) queries from a client-side web application to a remote server. These methods empower a web-based application to initiate server communications subsequent to page loading completion, and subsequently receive data back. XMLHttpRequest forms a foundational element of Ajax development. Before Ajax, primary means of server interaction involved navigating hyperlinks or submitting standard forms, which frequently resulted in a complete page refresh.

== Historical Context == The foundational concept for XMLHttpRequest originated in the year 2000, conceived by engineers working on Microsoft Outlook. This concept was subsequently integrated into the Internet Explorer 5 browser release (1999). However, the initial syntax did not utilize the 'XMLHttpRequest' literal; instead, developers employed object instantiation via ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (2006), universal browser support for the standard XMLHttpRequest identifier was achieved. The XMLHttpRequest identifier has since become the recognized convention across all major browser engines, including Mozilla's Gecko (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) formalized the XMLHttpRequest object specification with a Working Draft released on April 5, 2006. A Level 2 specification followed on February 25, 2008, introducing enhancements such as progress monitoring, enabling cross-origin requests, and processing of raw byte streams. By the close of 2011, the Level 2 features were incorporated back into the primary specification document. As of late 2012, development transitioned to the WHATWG, which now maintains an active specification document utilizing Web IDL.

== Operational Flow == Generally, executing a request utilizing XMLHttpRequest involves several distinct programming stages.

1. Instantiate the XMLHttpRequest object via its constructor:
2. Invoking the "open" method to define the request method (type), specify the target Uniform Resource Identifier (URI), and select blocking (synchronous) or non-blocking (asynchronous) execution:
3. For asynchronous operations, establishing an event handler function that is triggered upon changes in the request's state:
4. Triggering the actual network dispatch by calling the "send" method:
5. Monitoring state transitions within the designated event handler. If the server returns data, it is typically accumulated in the "responseText" attribute by default. When the request cycle concludes processing, the state transitions to 4, signifying the "done" condition. Beyond these fundamental steps, XMLHttpRequest offers numerous parameters to govern request transmission and response handling. Custom header fields can be appended to dictate server processing behavior, and payload data can be transmitted server-side by inclusion in the "send" argument. The returned data stream can be deserialized from JSON format into a native JavaScript object structure, or processed incrementally as segments arrive instead of awaiting the full payload. Furthermore, the request can be halted prematurely or configured to automatically time out if completion is not achieved within a preset duration.

== Cross-Origin Transactions ==

Early in the evolution of the World Wide Web, mechanisms were discovered that permitted information leakage across domain boundaries, leading to security concerns, which necessitated restrictions on how a script loaded from one origin could interact with resources hosted on another origin.