ynab

This MCP server provides a secure bridge between your YNAB budget data and AI assistants via the Model Context Protocol. It exposes a suite of tools that let you read budgets, accounts, categories, and perform transactions and analyses through natural language commands. Tools cover core operations (get_budgets, get_accounts, get_categories), transaction management (create_transaction, update_transaction, clear_transaction, approve_transaction), analysis (analyze_transactions, analyze_spending_by_category, get_transactions_by_date_range), budget operations (set_category_budget, create_transfer), and system utilities (health_check, cache_management). You can invoke these tools through an MCP client by pointing the client configuration at the ynab MCP server, either via a Docker-based image or a local binary, and then sending requests in the MCP protocol format. Typical usage includes asking the assistant to create transactions, query spending patterns, or transfer funds between accounts, all while respecting the Read-only mode when enabled for safe testing.

To configure the MCP client, add the ynab server reference to your client’s config, for example in Claude Desktop or VS Code integration, and specify the command or image you use to run the server. Once connected, you can ask natural language questions like: “Show my biggest expense categories this quarter,” “Transfer $500 from checking to savings,” or “Generate a spending report for the last month.” The server handles authentication via YNAB tokens stored securely in the OS keyring and enforces safe, read-only modes when configured.

Prerequisites:

• Docker (recommended) or a local build environment for the Ynab MCP server
• YNAB API token for authenticating with the YNAB API

Option A: Install and run via Docker

1. Ensure Docker is installed and running.

2. Run the MCP server in a container, providing your YNAB API token:

   docker run --rm -i -e YNAB_API_TOKEN="your-token" ghcr.io/cinnes/ynab-mcp:latest

Option B: Build from source (Rust) and run locally

1. Install Rust (1.70+): https://rustup.rs/

2. Clone the repository and build:

   git clone https://github.com/cinnes/ynab-mcp.git cd ynab-mcp cargo build --release

3. Run the built binary (adjust path as needed):

   ./target/release/ynab-mcp

Note: When running locally, ensure you pass the required environment variable YNAB_API_TOKEN or configure a secure storage method as documented.

Prerequisites recap:

• Docker or Rust toolchain
• Access to a YNAB API token
• Optional: keyring-backed token storage if not using Docker

Tips and common considerations:

• Tokens are stored securely in OS keyrings when using the provided authentication flow; ensure your environment grants access to the keyring.
• If you enable READ_ONLY_MODE, the server will prohibit data-modifying operations for safe testing.
• Set REQUEST_TIMEOUT_SECS to control HTTP request timeouts to YNAB’s API; defaults to 30 seconds.
• You can adjust logging via LOG_LEVEL to help with debugging in development environments (debug, info, warn, error).
• When using Docker, you can pass the token via an environment variable (YNAB_API_TOKEN) or mount a configuration secret as needed.
• If you encounter connectivity issues, verify that the YNAB API token is valid and that the container has network access to the YNAB API endpoints.
• Available tools span core operations, transaction management, analysis, budget operations, and system utilities; consult API docs for exact parameters and response formats.