MCP YNAB Server

A Model Context Protocol (MCP) server for integrating AI assistants with You Need A Budget (YNAB) API. Provides comprehensive budget management capabilities through tools, resources, and prompts.

Status: Phase 3 Week 2+ Testing - Write operations preview working, execution has bugs

Features

Budget Analysis & Reporting (35+ Tools)

16 Read-Only Tools + 19 Write Operation Tools (Phase 3)

• Budget Overview: Budget summaries, monthly views, category hierarchies, account listings
• Account Management: Account details, balances, transaction history
• Transaction Analysis: Advanced search, filtering, payee tracking, scheduled transactions
• Analysis & Reporting: Spending reports, cash flow analysis, goal tracking, net worth trends, overspending/underspending analysis

Optimized Tools (Response Size < 5KB)

• analyze_spending: Concise spending insights with configurable focus areas
• analyze_budget_health: Budget health assessment
• detect_anomalies: Unusual pattern detection

Intelligent Prompts (4 YAML-based prompts)

• ynab_checkup: 6-step comprehensive budget health assessment
• monthly_budget_review: Structured monthly performance analysis
• analyze_spending_patterns: Deep spending behavior analysis
• cash_balance_check: 5-step cash reconciliation verification

Write Operations (Phase 3 - Testing)

• Permission System: 5 permission levels from read-only to full write access
• Two-Stage Operations: Preview → Approve → Execute pattern with safety analysis
• Account Management: Create/update accounts
• Transaction Operations: Create/update/delete transactions (single and batch)
• Budget Planning: Update category budgets, move money between categories
• Scheduled Transactions: Create/update/delete scheduled transactions

Note: Preview stage working perfectly, execution stage has bugs being debugged.

Installation

Global Installation

npm install -g mcp-ynab

Development Installation

git clone https://github.com/richdooz/mcp-ynab.git
cd mcp-ynab
npm install

Configuration

Environment Variables

Create a .env file:

YNAB_API_KEY=your-ynab-personal-access-token
YNAB_BUDGET_ID=optional-specific-budget-id
YNAB_PERMISSION_LEVEL=2  # 0-4, controls write access

Permission Levels:

• 0: Read-only (default, safe for production)
• 1: Safe modifications (update memos/flags)
• 2: Standard operations (create transactions)
• 3: Advanced operations (modify transactions)
• 4: Full access (delete operations)

Getting a YNAB API Key:

1. Log in to YNAB
2. Go to Account Settings → Developer Settings
3. Generate a Personal Access Token

Usage

Development Mode

npm run dev        # Auto-reload on changes
npm run debug      # With verbose debug logging

Production Mode

npm start          # Stdio transport (default)

Standalone Testing

npm run test-standalone  # Test without MCP client

HTTP/HTTPS Mode (Streaming Support)

# Generate SSL certificates (first time only)
./generate-ssl-certs.sh

# Start HTTP server
./start-http.sh 3000

# Start HTTPS server
./start-http.sh 3443 https

MCP Client Configuration

Claude Desktop (Stdio - Recommended)

{
  "mcpServers": {
    "ynab": {
      "command": "node",
      "args": ["/path/to/mcp-ynab/src/index.js"],
      "env": {
        "YNAB_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Desktop (HTTP with Streaming)

{
  "mcpServers": {
    "ynab": {
      "command": "mcp-proxy",
      "args": ["http://localhost:3000/mcp"]
    }
  }
}

Note: HTTP mode requires mcp-proxy installed globally: npm install -g mcp-proxy

Architecture

Core Components

• ES Modules: Modern JavaScript with "type": "module"
• Entry Point: src/index.js
• Tools: Organized by category in src/tools/
• Shared Utilities: src/shared/ (ynab-client, cache-manager, error-handler, logger)
• Prompts: YAML-based system in src/prompts/

Key Features

• Intelligent Caching: 5-minute TTL for frequently accessed data
• Error Handling: Comprehensive retry logic and user-friendly messages
• Rate Limiting: Respects YNAB's 200 requests/hour limit
• MCP Compliance: File-based logging (no console output breaking JSON-RPC)

Available Tools

Budget Overview

• get_budget_summary - Comprehensive budget health snapshot
• get_budget_months - Available budget months with metrics
• get_categories - All categories with balances and goals
• list_budgets - All available budgets

Account Tools

• get_accounts - All accounts with balances
• get_account_details - Detailed single account information

Transaction Analysis

• get_transactions - Transaction history with filtering
• search_transactions - Advanced transaction search
• get_payees - All payees with spending analysis
• get_scheduled_transactions - Upcoming scheduled transactions

Analysis & Reporting

• get_spending_report - Comprehensive spending analysis
• get_cash_flow_analysis - Income vs expenses analysis
• get_goals_status - Goal progress tracking
• get_net_worth_trend - Net worth changes over time
• get_overspending_analysis - Overspending patterns
• get_underspending_analysis - Unused budget allocations
• analyze_spending - Optimized spending insights (< 2KB responses)
• analyze_budget_health - Budget health scoring
• detect_anomalies - Unusual pattern detection

Write Operations (Phase 3)

• preview_create_account - Preview new account creation
• preview_create_transaction - Preview new transaction
• preview_update_transaction - Preview transaction update
• preview_delete_transaction - Preview transaction deletion
• preview_create_multiple_transactions - Preview batch creation
• preview_update_category_budget - Preview budget update
• preview_move_money_between_categories - Preview money movement
• execute_write_operation - Execute approved operation (has bugs)

Full tool list: Run npm run list-tools (if available) or check src/tools/

Debugging

Debug logs are written to /tmp/mcp-ynab-debug.log (never to console - this breaks MCP protocol).

# Enable debug logging
MCP_DEBUG=true npm start

# View logs
tail -f /tmp/mcp-ynab-debug.log

See DEBUG.md for comprehensive debugging guide.

Development

Code Standards

• ES Modules with async/await patterns
• Node.js >= 18.0.0 required
• JSON Schema parameter validation
• MCP-compliant (no console output during normal operation)
• Comprehensive error handling

Project Structure

src/
├── index.js                    # Main MCP server entry point
├── shared/                     # Shared utilities
│   ├── ynab-client.js         # YNAB API wrapper
│   ├── cache-manager.js       # Intelligent caching
│   ├── error-handler.js       # Error handling
│   ├── logger.js              # File-based logging
│   └── ...                    # Permission, safety, approval managers
├── tools/                      # MCP tools organized by category
│   ├── budget-overview/
│   ├── account-tools/
│   ├── transaction-analysis/
│   ├── analysis-reporting/
│   └── write-operations/
├── prompts/                    # YAML prompt templates
└── config/                     # Configuration files

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes following code standards
4. Test with npm run test-standalone
5. Submit a pull request

Requirements

• Node.js: >= 18.0.0
• YNAB Account: With Personal Access Token
• MCP Client: Claude Desktop, or other MCP-compatible client

Documentation

• CLAUDE.md: Detailed architecture and developer guide
• PRD.md: Product requirements and development roadmap
• DEBUG.md: Debugging and troubleshooting guide
• TOOL_USAGE_GUIDE.md: Guide for using optimized vs verbose tools
• docs/archive/: Historical development journals and plans

License

MIT License - see LICENSE file for details

Support

• Developer: Rich Dozier [email protected]
• Issues: https://github.com/richdooz/mcp-ynab/issues
• Repository: https://github.com/richdooz/mcp-ynab

Current Development Status

Phase 1: ✅ Complete - 16 read-only tools implemented Phase 2: ✅ Complete - YAML prompt system with 4 intelligent prompts Phase 3: 🚧 Week 2+ Testing - 19 write operation tools (preview working, execution has bugs)

See PRD.md for detailed development roadmap and status.

Last Updated: 2025-10-12 Version: Phase 3 Week 2+ Testing