Ynab Mcp Server

What is Ynab Mcp Server about?

Enables AI assistants to securely access a user's YNAB financial information—such as budgets, accounts, categories, and transactions—through a locally‑hosted MCP server. The server mediates calls to the YNAB API, keeping the API token private while offering rich, contextual data for AI‑driven analysis.

How to use Ynab Mcp Server?

1. Prerequisites: Have a YNAB account with an API token and Docker (or .NET 9 SDK) installed.
2. Installation (preferred via Smithery):

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

   This configures VS Code to run the server in a Docker container.
3. Run the server: Press F5 in VS Code or start the Docker container manually.
4. Provide the token when prompted (environment variable YNAB_API_TOKEN).
5. Call MCP tools from a compatible client (e.g., Claude for Desktop) using the exposed functions.

Key features of Ynab Mcp Server

• User & Budget tools: GetUserInfo, ListBudgets, GetBudgetDetails, GetBudgetMonths
• Category & Transaction tools: ListCategories, GetCategoryDetails, SearchTransactions, ListAccountTransactions
• Account & Payee tools: ListAccounts, ListPayees
• Financial analysis tools: GetCurrentMonthSnapshot, GetRecentActivitySummary, GetIncomeVsExpenseSummary
• Docker image for easy deployment and isolation.
• Environment‑variable based security – the YNAB token never leaves the local machine.

Use cases of Ynab Mcp Server

• Personal finance assistants: AI can answer “How much did I spend on groceries last month?” by querying actual YNAB data.
• Budget forecasting: AI can suggest adjustments based on recent spending patterns.
• Goal tracking: Retrieve progress toward savings goals directly from YNAB.
• Automated reporting: Generate monthly financial summaries for personal review or sharing.

FAQ from the Ynab Mcp Server

• Do I need to expose my YNAB token to the internet? No. The server runs locally and only communicates with YNAB’s API over HTTPS.
• Can I run the server without Docker? Yes, with the .NET 9 SDK you can build and run the project directly.
• What clients are compatible? Any MCP‑compatible client, such as Claude for Desktop, can call the provided tools.
• How are new tools added? Implement a method in YnabTools.cs, decorate it with [McpServerTool] and [Description], then rebuild.
• Is the project open source? Yes, it is licensed under the MIT License.

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:

1. Access real-time data beyond their training cutoff date
2. Call functions in external systems
3. Interact with APIs securely
4. 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:

1. Configure VS Code to use the YNAB MCP Server Docker image
2. Prompt you for your YNAB API token when needed
3. 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:

1. Add new methods to YnabTools.cs
2. Decorate them with [McpServerTool] and [Description] attributes
3. 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.

Acknowledgments

• YNAB API
• Model Context Protocol
• Semantic Release