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
• 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

bashCopy code
# Install dependencies
npm install

# Build the project
npm run build

Project Structure

Copy code
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:

Copy code
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:

bashCopy code
# 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:

typescriptCopy code
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

1. 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

2. Build and test locally:

   bashCopy code
   npm run build
   npm link
   ynab-mcp-server  # Test your CLI locally
   

3. Login to npm (create account if necessary):

   bashCopy code
   npm login
   

4. Publish your package:

   bashCopy code
   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:

bashCopy code
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

jsonCopy code
{
  "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

jsonCopy code
{
  "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

1. Make changes to your tools
2. Run npm run build to compile
3. The server will automatically load your tools on startup

Learn More

• MCP Framework Github
• MCP Framework Docs