en es ja ko zh

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.

Integrations

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 today
- requires GetBudget to be called first so we know the account id

move to using budget by month call instead of getting categories from the entire budget: https://api.ynab.com/v1#/Months/getBudgetMonth

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
├── 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 name is unique and follows npm naming conventions
- Set appropriate version
- Add description, author, license, etc.
- Check bin points to the correct entry file
Build and test locally:
npm run build npm link ynab-mcp-server # Test your CLI locally
Login to npm (create account if necessary):
npm login
Publish 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

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 build to compile
The server will automatically load your tools on startup

Learn More

You must be authenticated.

A

security – no known vulnerabilities

A

license - permissive license

A

quality - confirmed to work

Tools

ynab_list_budgets

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.

YNAB MCP Server