Model Context Protocol Adapter for YNAB

This component implements an MCP server instance providing programmatic access to the You Need A Budget (YNAB) personal finance application's capabilities.

Key Capabilities

• Query current ledger balances and transaction histories
• Initiate the recording of new financial entries
• Interact with YNAB datasets conforming to established MCP resource schemas

Deployment Procedure

Use uv to install the package in editable mode:

uv pip install -e .

Initial Setup Requirements

The adapter necessitates a valid YNAB Developer API key for operation. This credential set can be procured from the official YNAB Developer Settings portal.

The authentication token must be injected via one of the following mechanisms:

1. Environment variable: Set YNAB_API_KEY=your_secret_key
2. Integration with MCP's secrets management subsystem
3. Definition within a .env file located in the root directory

Operational Guide

Launching the Backend Service

For iterative development cycles, including file watching and automatic browser invocation:

task dev

For deployment within secured environments like Claude Desktop or any compliant MCP host runtime:

task install

Accessible MCP Endpoints

• ynab://accounts - Retrieves a manifest of all linked YNAB accounts.
• ynab://transactions/{account_id} - Fetches the most recent ledger movements for a specified account identifier.

Exposed Functions (Tools)

• record_new_transaction - Logs a fresh expenditure or income event.
• fetch_account_valuation - Returns the present monetary standing for a designated account.

Practical Utilization Examples

# Registering a disbursement
outcome = await record_new_transaction(
    account_id="main_checking_123",
    value=-42.50,  # Denominated in currency units
    payee="Local Bistro",
    classification="Food/Restaurant",
    notes="Lunch meeting expense"
)

# Obtaining the current account worth
valuation = await fetch_account_valuation("main_checking_123")

# Enumerating all managed accounts
all_ledgers = await ctx.read_resource("ynab://accounts")

# Retrieving transaction history feed
recent_movements = await ctx.read_resource(f"ynab://transactions/{account_id}")

Maintenance and Quality Assurance

# Bootstrap project dependencies (using uv)
task deps

# Execute all testing suites, including live service interactions (requires API key)
task test:all

# Generate code quality/coverage metrics
task coverage

# Apply code formatting and linting rules
task fmt  # Consider adding this task definition

Project Orchestration

This project leverages a Taskfile.yml to streamline routine operational commands:

task dev       # Initiate development server with live reloading capabilities
task test      # Execute isolated unit verification routines
task coverage  # Produce a report on code execution pathways
task install   # Prepare the production-ready package artifact
task deps      # Synchronize and update dependency list

Refer to the configuration file, Taskfile.yml, for the complete command set.