Bulletninja/mcp-ynab
If you are the rightful owner of mcp-ynab and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.
MCP YNAB Server is a TypeScript implementation of the Model Context Protocol for interacting with YNAB data.
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:
- : Lists your available budgets.
- : Lists accounts within a specified budget.
- : Fetches the current balance for a specific account.
- : Lists categories within a specified budget.
- : Gets detailed information about a specific category for a given month.
- : Provides a budget summary (income, budgeted, activity) for a specific month.
- : Lists transactions for a budget, with filtering options (by account, category, date, etc.).
- : 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 ๐
-
Clone the Repository:
# git clone https://github.com/Bulletninja/mcp-ynab # If you haven't already cd mcp-ynab -
Install Dependencies:
npm install -
Configure Your YNAB API Token: You need a Personal Access Token from YNAB. The recommended and tested way for Cursor integration is:
- Edit your global Cursor configuration file
~/.cursor/mcp.json. - Add or modify the entry for
mcp-ynab, ensuring thecommand,args,cwd, andenvare correct:{ "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 ... } } - Alternative (requires code modification): You could use a
.envfile in the project root, but you would need to uncomment thedotenvlogic insrc/server.tsand ensure it doesn't interfere with server mode.
- Edit your global Cursor configuration file
-
Compile the Code:
npm run build
4. Usage with Cursor ๐ก
- Ensure the configuration in
~/.cursor/mcp.jsonis correct and"enabled": true. - Restart Cursor to load the updated configuration and launch the server.
- Done! In Cursor's MCP settings, you should see
mcp-ynabwith a green dot and the list of available tools. - You can now ask the AI assistant to use the tools:
- "List my YNAB budgets"
- "Use
mcp_ynab_list_accountswith 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-budgetsis commented out insrc/server.tsbecause 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.
