MCP Ledger Adapter for YNAB

This component functions as a server implementation adhering to the Model Context Protocol (MCP), granting programmatic access to the capabilities of You Need A Budget (YNAB).

Core Capabilities

• Inquire about current account valuations and detailed transaction histories.
• Facilitate the recording of novel fiscal movements.
• Access YNAB data through structured, protocol-defined resources.

Deployment

Installation via dependency manager:

uv pip install -e .

Configuration Mandates

The adapter necessitates a valid YNAB Access Token for operation. These keys are provisioned from your YNAB Developer Configuration portal.

Authorization credential injection methods:

1. As an environment variable: YNAB_API_KEY=your_secret_token
2. Via the designated MCP credential vault mechanism.
3. Within a local .env configuration file in the project root directory.

Operational Use

Initiating the Service

# For active development with live code reloading and UI spawning
task dev

# For deployment readiness in environments like Claude Desktop or Goose
task install

Accessible Endpoints (Resources)

• ynab://accounts - Fetches a roster of all configured YNAB financial holding accounts.
• ynab://transactions/{account_id} - Retrieves a ledger of recent activities associated with a specific account identifier.

Available Operations (Tools)

• create_transaction - Records a new entry into the ledger.
• get_account_balance - Queries the present monetary standing of a designated account.

Usage Demonstration

# Booking a new expenditure
record = await create_transaction(
    account_id="user_account_123",
    amount=-42.50,  # Denoted in USD
    payee_name="Local Eatery",
    category_name="Food & Drink",
    memo="Lunch expense"
)

# Checking a specific account's reserve
valuation = await get_account_balance("user_account_123")

# Listing all financial containers
container_list = await ctx.read_resource("ynab://accounts")

# Reviewing past movements
activity_log = await ctx.read_resource(f"ynab://transactions/{account_id}")

Maintenance and Review

# Install required libraries (utilizing uv)
task deps

# Execute all validation suites, including interactions with the live service (Requires API key)
task test:all

# Produce a report detailing code execution coverage
task coverage

# Standardize code style and check for static analysis errors
task fmt  # Recommend adding this to Taskfile configuration

Project Scripting Reference

This repository leverages Taskfile.yml for streamlined administrative actions:

task dev       # Launch server in development mode with automatic restarts
task test      # Execute unit-level software validation
task coverage  # Generate code coverage metrics
task install   # Prepare distribution package
task deps      # Synchronize the dependency tree

Consult Taskfile.yml for the complete set of available automation routines.