You Need A Budget (Unofficial) - Claude Desktop Extension
A comprehensive Claude Desktop Extension that provides seamless integration with You Need A Budget, enabling you to manage your complete budgeting workflow directly from Claude conversations using the YNAB API.
> Note: This is an unofficial extension and is not affiliated with or endorsed by You Need A Budget.
Quick Start
Installation
-
Get YNAB API Token from YNAB Developer Settings
- Click "New Token"
- Give it a name (e.g., "Claude Desktop")
- Copy the generated token -
Download the
ynab-mcpb.mcpbfile from the latest release -
Install in Claude Desktop (Settings → Extensions → Install Extension)
- Select the downloaded.mcpbfile
- When prompted, paste your YNAB API Token -
Start using YNAB tools in your conversations!
> 💡 Pro Tip: Use 'last-used' as the budget_id to access your most recently used budget.
Features
🎯 Core Functionality
- Complete Budget Management: View and manage all your budgets
- Account Operations: Access all accounts, create new ones, and view balances
- Category Management: View categories, set budgeted amounts, and track spending
- Transaction Management: Create, read, update, and delete transactions
- Advanced Filtering: Filter transactions by account, category, payee, or date range
🔍 Discovery & Navigation
- Payee Management: View all payees and their transaction history
- Scheduled Transactions: Access and review recurring transactions
- Monthly Budgets: View budget snapshots for any month
- Multi-Budget Support: Work with multiple budgets seamlessly
🛠️ Advanced Features
- Flexible Updates: Modify transactions and category budgets with full parameter control
- Data Integrity: Comprehensive input validation and error handling
- Security: Secure API token authentication
- Cross-Platform: Works on macOS, Linux, and Windows
API Reference
📊 Budgets
get_budgets - Get all budgets
Parameters: None
get_budget - Get budget details
Required: budget_id (use 'last-used' for most recent)
get_budget_settings - Get budget settings
Required: budget_id
💰 Accounts
get_accounts - Get all accounts
Required: budget_id
get_account - Get specific account
Required: budget_id, account_id
create_account - Create new account
Required: budget_id, name, type, balance
Types: checking, savings, creditCard, cash, lineOfCredit, otherAsset, otherLiability, mortgage, autoLoan, studentLoan, personalLoan, medicalDebt, otherDebt
📁 Categories
get_categories - Get all categories
Required: budget_id
get_category - Get specific category
Required: budget_id, category_id
get_category_for_month - Get category for specific month
Required: budget_id, month (YYYY-MM-DD), category_id
update_category_for_month - Update category budget
Required: budget_id, month (YYYY-MM-DD), category_id, budgeted (in milliunits)
💳 Transactions
> Note: For the transaction listing tools below, if since_date is omitted the YNAB API returns only the last year of transactions. Provide an explicit since_date to retrieve older transaction history.
get_transactions - Get transactions for a budget
Required: budget_id
Optional: since_date (YYYY-MM-DD), type (uncategorized, unapproved)
get_transaction - Get specific transaction
Required: budget_id, transaction_id
get_transactions_by_account - Get transactions for account
Required: budget_id, account_id
Optional: since_date
get_transactions_by_category - Get transactions for category
Required: budget_id, category_id
Optional: since_date
get_transactions_by_payee - Get transactions for payee
Required: budget_id, payee_id
Optional: since_date
create_transaction - Create new transaction
Required: budget_id, account_id, date (YYYY-MM-DD), amount (in milliunits)
Optional: payee_id, payee_name, category_id, memo, cleared, approved, flag_color
update_transaction - Update transaction
Required: budget_id, transaction_id
Optional: account_id, date, amount, payee_id, category_id, memo, cleared, approved, flag_color
delete_transaction - Delete transaction
Required: budget_id, transaction_id
🔄 Scheduled Transactions
get_scheduled_transactions - Get all scheduled transactions
Required: budget_id
get_scheduled_transaction - Get specific scheduled transaction
Required: budget_id, scheduled_transaction_id
👥 Payees
get_payees - Get all payees
Required: budget_id
get_payee - Get specific payee
Required: budget_id, payee_id
📅 Months
get_months - Get all months
Required: budget_id
get_month - Get specific month
Required: budget_id, month (YYYY-MM-DD or 'current')
Usage Examples
Budget Overview```
Show me an overview of my current budget, including all categories and how much I've budgeted vs. spent
### Transaction Management```
Create a transaction for $45.32 at Whole Foods in my checking account, categorized as Groceries, dated today
Spending Analysis```
Show me all my dining out transactions from the past 30 days and calculate how much I've spent
### Category Management```
Set my Groceries category budget to $500 for this month
Account Balances```
What are the balances of all my accounts?
### Monthly Review```
Show me my budget for this month and highlight any categories where I'm overspending
Important Concepts
Milliunits
YNAB API uses "milliunits" for all currency amounts:
- 1000 milliunits = $1.00
- Example: $45.32 = 45,320 milliunits
- Inflow (income) = positive values
- Outflow (expenses) = negative values
Budget ID
- Use
'last-used'to automatically use your most recently accessed budget - Or provide the specific budget ID from
get_budgets
Date Format
- All dates use ISO format:
YYYY-MM-DD - Example:
'2025-01-15'for January 15, 2025 - For months: Use the first day of the month (e.g.,
'2025-01-01'for January 2025)
Transaction Status
- cleared:
cleared,uncleared,reconciled - approved:
trueorfalse(default:falsefor new transactions) - flag_color:
red,orange,yellow,green,blue,purple, ornull
Requirements
- Node.js: Version 18.0.0 or higher
- YNAB Account: Active YNAB subscription
- YNAB API Token: Personal Access Token from YNAB Developer Settings
- Claude Desktop: Compatible with MCPB specification
- Internet Connection: Required for API access
Development
Building from Source```bash
Clone the repository
git clone https://github.com/mbmccormick/ynab-mcpb.git
cd ynab-mcpb
Install dependencies
npm install
Validate the code
npm run validate
Package the extension
npm run package
This will create `ynab-mcpb.mcpb` which you can install in Claude Desktop.
### Running Tests```bash
# Set your API token for testing
export YNAB_API_TOKEN="your-personal-access-token"
# Run validation tests
node test/test-validation.js
# Run error handling tests
node test/test-error-handling.js
Getting Your API Token
- Visit YNAB Developer Settings
- Click "New Token"
- Give it a name (e.g., "Claude Desktop")
- Copy the generated token
- Use it during installation or for testing
Architecture
Project Structure```
ynab-mcpb/
├── manifest.json # MCPB extension manifest
├── package.json # Dependencies and scripts
├── README.md # Documentation
├── .mcp.json # MCP configuration
├── .gitignore # Git ignore rules
└── server/
├── index.js # Main MCP server
├── tool-definitions.js # MCP tool schemas
├── ynab-client.js # YNAB API client
├── server-config.js # Configuration constants
└── utils.js # Utilities and helpers
### Key Design Principles
- **Separation of Concerns**: Modular architecture with clear responsibilities
- **Security First**: Secure API token handling and HTTPS communication
- **User-Friendly**: Intuitive parameter names and helpful error messages
- **Robust Error Handling**: Comprehensive error catching and reporting
- **Cross-Platform**: Works on all major operating systems
- **Extensible**: Easy to add new tools and functionality
- **Modern JavaScript**: ES6 modules with async/await
## Security Features
- **API Token Security**: Token stored in environment variables, never in code
- **HTTPS Communication**: All API requests use secure HTTPS
- **Input Validation**: All parameters validated for type and format
- **Error Handling**: Structured error responses with detailed logging
- **Timeout Management**: Prevents hanging API requests (30s default)
- **Rate Limiting**: Respects YNAB API rate limits (200 requests/hour)
## Development
### Running in Development Mode```bash
# Enable debug logging
DEBUG=true npm start
# Or use the dev script
npm run dev
Validating Code```bash
npm run validate
### Testing the Extension```bash
# Start the server
npm start
# The server will listen on stdio for MCP requests
Troubleshooting
Common Issues
API Token Not Set```
Error: YNAB_API_TOKEN environment variable is required
Solution: Set the YNAB_API_TOKEN environment variable or add it to .mcp.json
**Invalid API Token**```
Error: YNAB API error (401): Unauthorized
Solution: Verify your API token is correct at https://app.ynab.com/settings/developer
Rate Limit Exceeded```
Error: YNAB API error (429): Too Many Requests
Solution: Wait a few minutes. YNAB allows 200 requests per hour per token.
**Network Errors**```
Error: YNAB API request failed
Solution: Check your internet connection and verify YNAB service status
Debug Information```bash
Enable detailed logging
DEBUG=true npm start
```
Getting Help
- YNAB API Issues: Check YNAB API Documentation
- Claude Desktop: Follow Claude Desktop documentation
- Extension Issues: Create issue in project repository
API Rate Limits
- Limit: 200 requests per hour per access token
- Recommendation: Use delta requests when possible to reduce API calls
- Best Practice: Cache frequently accessed data
License
MIT License - See package.json for details
Acknowledgments
- YNAB for their excellent API and budgeting platform
- Anthropic for the Model Context Protocol (MCP) SDK
- Community for feedback and contributions
Built with ❤️ for the Claude Desktop ecosystem
