Actual Budget MCP Server

Let Claude manage your budget! This is a Model Context Protocol (MCP) server that allows AI assistants to interact with your Actual Budget.

Features

Manage your budget through natural language conversations with Claude:

• 📝 Add Transactions - "Add a transaction: $350 at Whole Foods for groceries"

• 💰 Check Balances - "What's my checking account balance?"

• 🔄 Transfer Money - "Transfer $500 from checking to savings"

• 📊 Budget Tracking - "How much have I spent on dining this month?"

• 🔍 Search Transactions - "Show me all Costco purchases last month"

• 📈 Spending Analysis - "Analyze my spending breakdown for this month"

• 📥 Batch Import - Import multiple transactions from CSV or structured data

Supported Tools

Quick Start

Prerequisites

• Running Actual Budget server

• Password authentication (OpenID users need to enable password login)

• Docker (for deployment)

1. Get Budget Sync ID

In Actual Budget:

1. Go to Settings

2. Click Show advanced settings

3. Copy the Sync ID

2. Configure Environment Variables

Edit .env:

3. Deploy with Docker

Or use Docker Compose:

4. Connect to Claude

Configure the Connector in claude.ai:

1. Go to Settings → Connectors

2. Click Add Connector

3. Select MCP

4. Enter URL: http://your-server:3000/mcp

TrueNAS Scale Deployment

Using Custom App

1. In TrueNAS Scale, go to Apps → Discover Apps → Custom App

2. Configure as follows:

   Application Name: actual-budget-mcp

   Image Repository: Your Docker registry or local build

   Container Images:

   • Image: actual-budget-mcp:latest

   Container Environment Variables:

   ACTUAL_SERVER_URL=http://actual-budget:5006 ACTUAL_PASSWORD=your-password ACTUAL_BUDGET_ID=your-sync-id

   Networking:

   • Port: 3000 → 3000 (TCP)

   Storage:

   • Host Path: /mnt/your-pool/actual-mcp-cache

   • Mount Path: /data/actual-cache

3. If Actual Budget is also on TrueNAS, ensure they're on the same network.

Integration with Existing Actual Budget

If your Actual Budget is already deployed on TrueNAS:

Local Development

API Endpoints

Usage Examples

After configuring the Connector, you can interact with Claude like this:

Adding a Regular Transaction

Transferring Between Accounts

Batch Importing Transactions

Viewing Budget Status

New Features in v1.2.0

Transfer Transactions

The add_transaction tool now supports the transfer_to parameter for creating transfers between accounts:

This automatically creates matching transactions in both accounts using Actual Budget's transfer mechanism.

Batch Import Transactions

The new import_transactions tool allows bulk importing of transactions with improved performance:

Benefits:

• Single API call instead of multiple individual calls

• Better duplicate detection using imported_id

• Proper rule application across entire batch

• Returns detailed counts of added/updated transactions

Troubleshooting

Connection Failed

1. Verify Actual Budget server is running

2. Check that ACTUAL_SERVER_URL is correct

3. If using Docker networking, verify container names are correct

Authentication Failed

1. Verify password is correct

2. If using OpenID, ensure password login is also enabled:

   // config.json { "allowedLoginMethods": ["password", "openid"] }

Budget Not Found

1. Verify ACTUAL_BUDGET_ID is the correct Sync ID

2. Find Sync ID in Actual Budget's Settings → Show advanced settings

Encryption Error

If your budget has end-to-end encryption enabled, you need to set ACTUAL_ENCRYPTION_PASSWORD

License

MIT License

Related Resources

• Actual Budget

• Actual Budget API Documentation

• Model Context Protocol

• MCP TypeScript SDK