ynab-mcp-server

SonOfSamuel1/ynab-mcp-server

3.2

If you are the rightful owner of ynab-mcp-server 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.

A Model Context Protocol (MCP) server for integrating YNAB (You Need A Budget) with Claude and other MCP clients.

Tools
12
Resources
0
Prompts
0

YNAB MCP Server

A Model Context Protocol (MCP) server for integrating YNAB (You Need A Budget) with Claude and other MCP clients.

Features

  • Full TypeScript implementation with comprehensive error handling
  • 12 tools for managing budgets, accounts, categories, and transactions
  • Support for both stdio and HTTP transports
  • JSON and Markdown output formats
  • Built on the official MCP SDK

Installation

Prerequisites

  • Node.js 18 or higher
  • A YNAB account with API access
  • YNAB Personal Access Token

Setup

  1. Install dependencies:
npm install
  1. Build the project:
npm run build

  1. Get your YNAB Personal Access Token:

    • Visit https://app.ynab.com
    • Go to Account Settings → Developer Settings
    • Click New Token
    • Copy your token

  2. Set up your environment:

export YNAB_ACCESS_TOKEN='your-token-here'

Or create a .env file:

YNAB_ACCESS_TOKEN=your-token-here

Usage

Running the Server

npm start

Claude Desktop Integration

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ynab": {
      "command": "node",
      "args": ["/absolute/path/to/ynab-mcp-server/dist/index.js"],
      "env": {
        "YNAB_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Available Tools

Budget Tools

ynab_list_budgets

List all available budgets.

Parameters:

  • format (optional): Output format - "json" or "markdown" (default: "json")

Example:

Show me all my YNAB budgets
ynab_get_budget

Get detailed information about a specific budget.

Parameters:

  • budget_id (required): Budget ID or "last-used"
  • format (optional): Output format - "json" or "markdown"

Example:

Show me details for my last-used budget

Account Tools

ynab_list_accounts

List all accounts in a budget.

Parameters:

  • budget_id (required): Budget ID or "last-used"
  • format (optional): Output format

Example:

List all accounts in my last-used budget
ynab_get_account

Get details for a specific account.

Parameters:

  • budget_id (required): Budget ID or "last-used"
  • account_id (required): Account ID
  • format (optional): Output format

Example:

Show me details for account [account-id] in my budget
ynab_create_account

Create a new account in a budget.

Parameters:

  • budget_id (required): Budget ID or "last-used"
  • name (required): Account name
  • type (required): Account type - "checking", "savings", "creditCard", "cash", "lineOfCredit", "otherAsset", "otherLiability"
  • balance (required): Starting balance in milliunits

Example:

Create a new checking account called "New Bank" with a balance of $1000

Category Tools

ynab_list_categories

List all categories and category groups in a budget.

Parameters:

  • budget_id (required): Budget ID or "last-used"
  • format (optional): Output format

Example:

Show me all categories in my budget
ynab_update_category_budget

Update the budgeted amount for a category in a specific month.

Parameters:

  • budget_id (required): Budget ID or "last-used"
  • month (required): Month in ISO format (YYYY-MM-DD)
  • category_id (required): Category ID
  • budgeted (required): Budgeted amount in milliunits

Example:

Set the groceries category budget to $500 for this month

Transaction Tools

ynab_list_transactions

List transactions in a budget.

Parameters:

  • budget_id (required): Budget ID or "last-used"
  • since_date (optional): Only return transactions on or after this date (ISO format)
  • account_id (optional): Filter by account ID
  • format (optional): Output format

Example:

Show me all transactions from the last 30 days
ynab_get_transaction

Get details for a specific transaction.

Parameters:

  • budget_id (required): Budget ID or "last-used"
  • transaction_id (required): Transaction ID
  • format (optional): Output format

Example:

Show me details for transaction [transaction-id]
ynab_create_transaction

Create a new transaction.

Parameters:

  • budget_id (required): Budget ID or "last-used"
  • account_id (required): Account ID
  • date (required): Transaction date (ISO format: YYYY-MM-DD)
  • amount (required): Amount in milliunits (negative for outflow/expense, positive for inflow/income)
  • payee_name (optional): Payee name
  • category_id (optional): Category ID
  • memo (optional): Transaction memo

Example:

Add a $50 expense to my checking account for groceries today
ynab_update_transaction

Update an existing transaction.

Parameters:

  • budget_id (required): Budget ID or "last-used"
  • transaction_id (required): Transaction ID
  • account_id (optional): Account ID
  • date (optional): Transaction date (ISO format)
  • amount (optional): Amount in milliunits
  • payee_name (optional): Payee name
  • category_id (optional): Category ID
  • memo (optional): Transaction memo

Example:

Update transaction [transaction-id] to change the amount to $75
ynab_delete_transaction

Delete a transaction.

Parameters:

  • budget_id (required): Budget ID or "last-used"
  • transaction_id (required): Transaction ID

Example:

Delete transaction [transaction-id]

Currency Format: Milliunits

YNAB uses "milliunits" for all currency amounts:

  • $1.00 = 1000 milliunits
  • $10.50 = 10500 milliunits
  • $100.00 = 100000 milliunits

For transactions:

  • Negative amounts = outflows (expenses)
  • Positive amounts = inflows (income)

Examples:

$50.00 expense = -50000 milliunits
$1,234.56 income = 1234560 milliunits

Development

Build

npm run build

Watch Mode

npm run dev

Project Structure

ynab-mcp-server/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript output
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── .env                  # Environment variables (not in git)
├── .gitignore           # Git ignore rules
└── README.md            # This file

Error Handling

The server includes comprehensive error handling for:

  • Missing or invalid YNAB access tokens
  • Failed API requests
  • Invalid tool parameters
  • Network errors
  • YNAB API rate limits

All errors are returned with descriptive messages to help diagnose issues.

Security Notes

  • Never commit your .env file or expose your YNAB access token
  • Store tokens securely using environment variables
  • Tokens have full access to your YNAB account - treat them like passwords
  • You can revoke tokens at any time from YNAB's Developer Settings

Resources

License

MIT

Support

For issues or questions: