YNAB

What is YNAB MCP Server?

The YNAB MCP Server is a Model Context Protocol (MCP) server designed to bridge the gap between your YNAB (You Need A Budget) financial data and AI assistants. It enables AI models to securely access, analyze, and interact with your personal financial information, going beyond general knowledge to provide contextual analysis based on your specific data.

How to use YNAB MCP Server?

To use the YNAB MCP Server, you will need a YNAB account with API access and an MCP-compatible client (e.g., Claude for Desktop). You can install it via Smithery using npx -y @smithery/cli install @ChuckBryan/ynabmcpserver --client claude or directly in VS Code by clicking the provided installation badges. Once installed, you will be prompted for your YNAB API token, and the server will start automatically in a Docker container. The server runs locally on your machine, ensuring your YNAB API token and financial data remain private.

Key Features of YNAB MCP Server

The YNAB MCP Server offers a comprehensive set of tools for interacting with the YNAB API, including:

User and Budget Information: Retrieve user ID, list budgets, get budget details, and list budget months.
Categories and Transactions: List categories, get category details, search transactions with custom filters, and list account transactions.
Accounts and Payees: List accounts and payees.
Financial Analysis: Get a snapshot of the current month's budget, a summary of recent financial activity, and compare income to expenses over time.

Use Cases of YNAB MCP Server

This project allows you to:

Query your budget information.
Analyze spending patterns.
Check account balances.
Track financial goals.
Gain insights into your financial habits.

FAQ about YNAB MCP Server

What is MCP? The Model Context Protocol (MCP) is a standard that allows AI assistants to interact with external tools and services, enabling them to access real-time data, call functions in external systems, interact with APIs securely, and provide contextual analysis based on personal data.
Is my data secure? Yes, the MCP server runs locally on your machine and does not share your YNAB API token with third parties. The API token is only used to communicate directly with the YNAB API.
What are the prerequisites? A YNAB account with API access, an MCP-compatible client, and either Docker or the .NET 9 SDK for installation.
How can I contribute? Contributions are welcome! You can submit a Pull Request. Refer to the VERSIONING.md for details on the commit message format and release process.

YNAB MCP Server

A Model Context Protocol (MCP) server for integrating YNAB (You Need A Budget) with AI systems. This project allows AI assistants to securely access and analyze your YNAB financial data.

What is MCP?

The Model Context Protocol (MCP) is a standard that allows AI assistants to interact with external tools and services. It enables AI models like Claude to:

Access real-time data beyond their training cutoff date
Call functions in external systems
Interact with APIs securely
Provide contextual analysis based on your personal data

Instead of just answering based on general knowledge, MCP allows AI to work with your specific information.

About YNAB MCP Server

This project creates a secure bridge between your YNAB financial data and AI assistants. It allows you to:

Query your budget information
Analyze spending patterns
Check account balances
Track financial goals
Get insights about your financial habits

All while keeping your YNAB API token secure and your financial data private.

Features

This MCP server implements a comprehensive set of tools for interacting with the YNAB API:

User and Budget Information

GetUserInfo - Retrieve your YNAB user ID
ListBudgets - Get all budgets in your YNAB account
GetBudgetDetails - Detailed information about a specific budget
GetBudgetMonths - List budget months

Categories and Transactions

ListCategories - All categories in a budget
GetCategoryDetails - Detailed information about a category
SearchTransactions - Find transactions with custom filters
ListAccountTransactions - Get transactions for a specific account

Accounts and Payees

ListAccounts - Get all accounts in a budget
ListPayees - Get all payees in a budget

Financial Analysis

GetCurrentMonthSnapshot - Summary of the current month's budget
GetRecentActivitySummary - Summary of recent financial activity
GetIncomeVsExpenseSummary - Compare income to expenses over time

Getting Started

Prerequisites

YNAB Account with API access
An MCP-compatible client (e.g., Claude for Desktop)
Either:
- Docker (for Docker installation)
- .NET 9 SDK (for local installation)

Installation

Installing via Smithery

To install YNAB Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @ChuckBryan/ynabmcpserver --client claude

Click one of these buttons to automatically install the YNAB MCP Server in VS Code:

This will:

Configure VS Code to use the YNAB MCP Server Docker image
Prompt you for your YNAB API token when needed
Allow you to start the server with F5 or the Run menu

Once installed, you can start the server by pressing F5 in VS Code or using the Run menu. When prompted, enter your YNAB API token and the server will start automatically in a Docker container.

Available Environment Variables

YNAB_API_TOKEN: Your YNAB API token (required)

Security

This MCP server runs locally on your machine and does not share your YNAB API token with third parties. The API token is only used to communicate directly with the YNAB API.

Development

Project Structure

YnabMcpServer/
├── .vscode/            # VS Code configuration
├── docs/               # Documentation
├── requests/           # HTTP request samples for testing
├── scripts/            # Utility scripts
└── src/                # Source code
    └── YnabMcpServer/  # Main project
        ├── Configuration/ # Configuration classes
        ├── Generated/     # Generated API client code
        ├── Services/      # Service implementations
        ├── Tools/         # MCP tool implementations
        └── Program.cs     # Application entry point

Extending the Server

To add new MCP tools:

Add new methods to YnabTools.cs
Decorate them with [McpServerTool] and [Description] attributes
Rebuild and restart the server

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Versioning and Release Process

This project uses semantic-release for automated versioning and releases. See VERSIONING.md for details on the commit message format and release process.

YNAB Overview