Calebl Ynab MCP Server

🚀 ynab-mcp-server

A Model Context Protocol (MCP) server for the YNAB (You Need A Budget) budgeting tool, built on the mcp-framework. This MCP provides tools to interact with your YNAB budget set up at https://ynab.com.

To enable AI to interact with this tool, you need to obtain your personal access token: https://api.ynab.com/#personal-access-tokens. When adding this MCP server to any client, you need to provide your personal access token as YNAB_API_TOKEN. This token is never sent directly to the LLM (Large Language Model). It is securely stored in environment variables and used only for communicating with the YNAB API.

🚀 Quick Start

Prerequisites

To enable AI to interact with this tool, you need to obtain your personal access token: Personal Access Tokens. When adding this MCP server to any client, you need to provide your personal access token as YNAB_API_TOKEN.

Steps

1. Clone the repository:

git clone https://github.com/your-repository.git

2. Install dependencies:

npm install

3. Configure environment variables:

export YNAP_API_TOKEN=your_token_here

4. Run the server:

node dist/index.js

✨ Features

Key Features

• Budget Interaction: Allows AI to interact with your YNAB budget through conversations.
• Multiple Workflows: Supports various budget management workflows, such as budget selection, category management, and transaction handling.

Current Tools

• ListBudgets: Lists all available budgets.
• SetBudget: Sets the default budget.
• GetCategories: Retrieves budget categories.
• CreateCategory: Creates a new budget category.
• UpdateCategory: Updates an existing budget category.
• DeleteCategory: Deletes a budget category.

Future Plans

• Add transaction management features (CreateTransaction, UpdateTransaction, DeleteTransaction).
• Implement budget tracking and reporting.

📦 Installation

Environment Variables

• YNAP_API_TOKEN (Required): Your personal access token for the YNAB API.
• KNOWLEDGE_DIR (Optional): Directory to store knowledge files. Defaults to the data directory where the server runs.
• KNOWLEDGE_FILE (Optional): Name of the knowledge file. Defaults to server-knowledge.json.

💻 Usage Examples

First-time Setup

• You will be prompted to select your budget from the available ones. This prompt is triggered if you try to use this tool before using other tools, asking you to set a default budget.
  • Required Tools: ListBudgets, SetBudget

Other Workflows

• Manage Overspent Categories
• Add New Transactions
• Approve Transactions
• Check Total Monthly Expenses vs. Total Income
• Automatically Allocate Funds Based on Category Goals

📚 Documentation

Project Structure

.
├── src/
│   ├── tools/           # Directory for tools, containing tool classes for interacting with the YNAB API
│   │   └── ynabTools.ts
│   └── server.ts       # Main server file
├── package.json        # Project dependencies and scripts
└── README.md           # Project documentation

Adding Components

To add a new functional module:

1. Create a new tool class in the src/tools/ directory.
2. Implement the interaction logic with the YNAB API.
3. Update the server file to load the new tool.

Tool Development

The basic structure of a tool class:

export class YNABTools {
    private readonly token: string;

    constructor(token: string) {
        this.token = token;
    }

    // Implement specific functional methods
}

Publishing to npm

1. Log in to npm:

npm login

2. Submit a version update:

npm version patch

3. Publish a new version:

npm publish

Other MCP Clients

Check MCP Clients for more information.

Learn More

• MCP Framework Github
• MCP Framework Documentation

📄 License

No license information provided in the original document.

⚠️ Important Note

This token is never sent directly to the LLM (Large Language Model). It is securely stored in environment variables and used only for communicating with the YNAB API.