A
securityF
licenseA
qualityAn MCP server that allows users to interact with YNAB data, enabling access to account balances, transactions, and the creation of new transactions through the Model Context Protocol.
Last updated -
10
5
This YNAB MCP Server enables AI-driven interaction with your YNAB budgets. Key capabilities include:
List available budgets using the
ListBudgetstoolSummarize budget status to identify underfunded categories and low accounts
Retrieve and approve transactions (view unapproved transactions and approve them by ID)
Create new transactions for specified budgets and accounts
Manage workflows including:
First-time budget setup
Managing overspent categories
Checking monthly spending versus income
Auto-distributing funds based on category targets
Develop and add custom tools using the MCP framework and YNAB SDK
Supports publishing the MCP server as an npm package for easier distribution and installation
Used for building tools that interact with YNAB's API through typed interfaces
Utilized for schema validation of tool inputs when interacting with YNAB data
ynab-mcp-server
A Model Context Protocol (MCP) server built with mcp-framework. This MCP provides tools for interacting with your YNAB budgets setup at https://ynab.com
In order to have an AI interact with this tool, you will need to get your Personal Access Token from YNAB: https://api.ynab.com/#personal-access-tokens. When adding this MCP server to any client, you will need to provide your personal access token as YNAB_API_TOKEN. This token is never directly sent to the LLM. It is stored privately in an environment variable for use with the YNAB api.
Setup
Specify env variables:
YNAB_API_TOKEN (required)
YNAB_BUDGET_ID (optional)
Goal
The goal of the project is to be able to interact with my YNAB budget via an AI conversation. There are a few primary workflows I want to enable:
Workflows:
First time setup
be prompted to select your budget from your available budgets. If you try to use another tool first, this prompt should happen asking you to set your default budget.
Tools needed: ListBudgets
Manage overspent categories
Adding new transactions
Approving transactions
Check total monthly spending vs total income
Auto-distribute ready to assign funds based on category targets
Current state
Available tools:
ListBudgets - lists available budgets on your account
BudgetSummary - provides a summary of categories that are underfunded and accounts that are low
GetUnapprovedTransactions - retrieve all unapproved transactions
CreateTransaction - creates a transaction for a specified budget and account.
example prompt:
Add a transaction to my Ally account for $3.98 I spent at REI todayrequires GetBudget to be called first so we know the account id
ApproveTransaction - approves an existing transaction in your YNAB budget
requires a transaction ID to approve
can be used in conjunction with GetUnapprovedTransactions to approve pending transactions
After calling get unapproved transactions, prompt:
approve the transaction for $6.95 on the Apple Card
Next:
be able to approve multiple transactions with 1 call
updateCategory tool - or updateTransaction more general tool if I can get optional parameters to work correctly with zod & mcp framework
move off of mcp framework to use the model context protocol sdk directly?
Quick Start
# Install dependencies
npm install
# Build the project
npm run build
Project Structure
ynab-mcp-server/
├── src/
│ ├── tools/ # MCP Tools
│ └── index.ts # Server entry point
├── .cursor/
│ └── rules/ # Cursor AI rules for code generation
├── package.json
└── tsconfig.json
Adding Components
The YNAB sdk describes the available api endpoints: https://github.com/ynab/ynab-sdk-js.
YNAB open api specification is here: https://api.ynab.com/papi/open_api_spec.yaml. This can be used to prompt an AI to generate a new tool. Example prompt for Cursor Agent:
create a new tool based on the readme and this openapi doc: https://api.ynab.com/papi/open_api_spec.yaml
The new tool should get the details for a single budget
You can add more tools using the CLI:
# Add a new tool
mcp add tool my-tool
# Example tools you might create:
mcp add tool data-processor
mcp add tool api-client
mcp add tool file-handler
Tool Development
Example tool structure:
import { MCPTool } from "mcp-framework";
import { z } from "zod";
interface MyToolInput {
message: string;
}
class MyTool extends MCPTool<MyToolInput> {
name = "my_tool";
description = "Describes what your tool does";
schema = {
message: {
type: z.string(),
description: "Description of this input parameter",
},
};
async execute(input: MyToolInput) {
// Your tool logic here
return `Processed: ${input.message}`;
}
}
export default MyTool;
Publishing to npm
Update your package.json:
Ensure
nameis unique and follows npm naming conventionsSet appropriate
versionAdd
description,author,license, etc.Check
binpoints to the correct entry file
Build and test locally:
npm run build npm link ynab-mcp-server # Test your CLI locallyLogin to npm (create account if necessary):
npm loginPublish your package:
npm publish
After publishing, users can add it to their claude desktop client (read below) or run it with npx
Using with Claude Desktop
Installing via Smithery
To install YNAB Budget Assistant for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @calebl/ynab-mcp-server --client claude
Local Development
Add this configuration to your Claude Desktop config file:
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"ynab-mcp-server": {
"command": "node",
"args":["/absolute/path/to/ynab-mcp-server/dist/index.js"]
}
}
}
After Publishing
Add this configuration to your Claude Desktop config file:
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"ynab-mcp-server": {
"command": "npx",
"args": ["ynab-mcp-server"]
}
}
}
Other MCP Clients
Check https://modelcontextprotocol.io/clients for other available clients.
Building and Testing
Make changes to your tools
Run
npm run buildto compileThe server will automatically load your tools on startup
Learn More
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
A Model Context Protocol server that enables AI-powered interaction with YNAB (You Need A Budget) data, allowing users to query their budgets through conversational interfaces.
- Setup
- Goal
- Workflows:
- Current state
- Quick Start
- Project Structure
- Adding Components
- Tool Development
- Publishing to npm
- Using with Claude Desktop
- Building and Testing
- Learn More
Related Resources
Related MCP Servers
- AsecurityFlicenseAqualityProvides access to YNAB (You Need A Budget) functionality through the Model Context Protocol, allowing users to view account balances, access transaction data, and create new transactions.Last updated -10
- -securityAlicense-qualityA Model Context Protocol (MCP) server for interacting with YNAB (You Need A Budget). Provides tools for accessing budget data through MCP-enabled clients like Claude Desktop.Last updated -3MIT License