npm package: @richdooz/mcp-ynab
Description: Model Context Protocol server for YNAB integration
Author: Rich Dozier
Latest version: 1.6.4

# 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
```bash
npm install -g mcp-ynab
```

### Development Installation
```bash
git clone https://github.com/richdooz/mcp-ynab.git
cd mcp-ynab
npm install
```

## Configuration

### Environment Variables

Create a `.env` file:
```bash
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
```bash
npm run dev        # Auto-reload on changes
npm run debug      # With verbose debug logging
```

### Production Mode
```bash
npm start          # Stdio transport (default)
```

### Standalone Testing
```bash
npm run test-standalone  # Test without MCP client
```

### HTTP/HTTPS Mode (Streaming Support)
```bash
# 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)
```json
{
  "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)
```json
{
  "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).

```bash
# Enable debug logging
MCP_DEBUG=true npm start

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

See [DEBUG.md](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 <richdooz@gmail.com>
- **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](PRD.md) for detailed development roadmap and status.

---

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