MCP YNAB Server 💰

Welcome to the MCP server for YNAB (TypeScript version)! 🎉 This project allows you to connect Cursor (or another MCP client) to your You Need A Budget (YNAB) account to interact with your financial data directly from your editor.

1. What is this? 🤔 (Purpose)

This is an implementation of the Model Context Protocol (MCP) in TypeScript that acts as a bridge to the official YNAB API. The goal is to provide standardized tools for reading and writing YNAB data from MCP-compatible environments, allowing AI assistants like Cursor's to help you with your finances.

2. Available Tools 🛠️

This server provides the following tools, each with its own detailed documentation:

listBudgets: Lists your available budgets.
listAccounts: Lists accounts within a specified budget.
getAccountBalance: Fetches the current balance for a specific account.
listCategories: Lists categories within a specified budget.
getCategoryInfo: Gets detailed information about a specific category for a given month.
getBudgetSummary: Provides a budget summary (income, budgeted, activity) for a specific month.
listTransactions: Lists transactions for a budget, with filtering options (by account, category, date, etc.).
createTransaction: Creates a new transaction or split transaction within a budget.

See each tool's README.md for detailed information on arguments, output, and usage context.

3. Setup 🚀

1. Clone the Repository:

    # git clone https://github.com/Bulletninja/mcp-ynab # If you haven't already

    cd mcp-ynab 

    

    npm install

    

        {

          "mcpServers": {

            // ... other servers ...

            "mcp-ynab": {

              "command": "node",

              // 👇 Path to the compiled script

              "args": ["<path-to-your-project>/mcp-ynab/dist/server.js"], 

              "cwd": "<path-to-your-project>/mcp-ynab", // Path to this project

              "enabled": true,

              "env": {

                // 👇 Your YNAB token here, with the correct name!

                "YNAB_API_TOKEN": "YOUR_YNAB_TOKEN_HERE" 

              }

            }

            // ... other servers ...

          }

        }

        

    npm run build

    

1. Ensure the configuration in ~/.cursor/mcp.json is correct and "enabled": true.
2. Restart Cursor to load the updated configuration and launch the server.
3. Done! In Cursor's MCP settings, you should see mcp-ynab with a green dot and the list of available tools.
4. You can now ask the AI assistant to use the tools:
"List my YNAB budgets"
"Use mcp_ynab_list_accounts with budget_id 'last-used'"
"What's the balance of my account X (ID: YYY) in budget Z?" (Might use mcp_ynab_get_account_balance)

5. Development 🧑‍💻

Run server in development mode (with hot-reload): npm run dev
Run tests: npm test
Compile for production/MCP: npm run build
CLI Mode (Commented Out): The logic to run commands like node dist/server.js list-budgets is commented out in src/server.ts because it interfered with Cursor's MCP server mode. You can uncomment it for local testing if needed, but remember to comment it back out and recompile for Cursor integration.

---