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.