# Actual Budget MCP Server
Let Claude manage your budget! This is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that allows AI assistants to interact with your [Actual Budget](https://actualbudget.org/).
## 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
| Tool | Description |
|------|-------------|
| `get_accounts` | Get all accounts with balances |
| `get_account_balance` | Query specific account balance |
| `add_transaction` | Add transaction (income/expense/transfer) |
| `import_transactions` | Batch import multiple transactions |
| `get_transactions` | Query account transaction history |
| `search_transactions` | Search transactions by payee, notes, or amount |
| `update_transaction` | Update existing transaction |
| `delete_transaction` | Delete a transaction |
| `get_categories` | Get all budget categories |
| `get_budget_month` | View monthly budget overview |
| `set_budget_amount` | Set category budget amount |
| `get_payees` | Get all payees/merchants |
| `get_spending_summary` | Get spending summary analysis |
| `get_schedules` | View recurring transactions/bills |
| `create_schedule` | Create recurring transaction |
| `delete_schedule` | Delete recurring transaction |
| `sync_budget` | Sync budget data |
## 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
```bash
cp .env.example .env
```
Edit `.env`:
```env
ACTUAL_SERVER_URL=http://your-actual-server:5006
ACTUAL_PASSWORD=your-password
ACTUAL_BUDGET_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# If you have end-to-end encryption enabled
# ACTUAL_ENCRYPTION_PASSWORD=your-encryption-password
```
### 3. Deploy with Docker
```bash
# Build image
docker build -t actual-budget-mcp .
# Run
docker run -d \
--name actual-budget-mcp \
-p 3000:3000 \
--env-file .env \
actual-budget-mcp
```
Or use Docker Compose:
```bash
docker-compose up -d
```
### 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:
```yaml
# Configure network in docker-compose.yml
services:
actual-budget-mcp:
# ...
environment:
- ACTUAL_SERVER_URL=http://actual-budget:5006 # Use container name
networks:
- actual-network
networks:
actual-network:
external: true # Use existing network
```
## Local Development
```bash
# Install dependencies
npm install
# Development mode (requires .env)
npm run dev
# Build
npm run build
# Run
npm start
```
## API Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/mcp` | POST | MCP request endpoint |
| `/health` | GET | Health check |
## Usage Examples
After configuring the Connector, you can interact with Claude like this:
### Adding a Regular Transaction
```
You: Add a transaction: $180 at Starbucks yesterday
Claude: ✅ Transaction added:
- Account: Checking
- Amount: -$180
- Payee: Starbucks
- Date: 2024-12-29
Would you like to specify a category?
```
### Transferring Between Accounts
```
You: Transfer $500 from checking to savings
Claude: ✅ Transfer created:
- From: Checking
- To: Savings
- Amount: $500
- Date: 2024-12-30
The transfer has been recorded in both accounts.
```
### Batch Importing Transactions
```
You: Import these transactions to my checking account:
- Jan 1: $50 at Grocery Store (Food)
- Jan 2: $100 at Gas Station (Transportation)
- Jan 3: $25 at Coffee Shop (Dining)
Claude: ✅ Imported 3 transactions:
- Added: 3
- Updated: 0
All transactions have been imported successfully.
```
### Viewing Budget Status
```
You: How's my budget for this month?
Claude: Here's your budget summary for 2024-12:
📊 Overall Status
- To Budget: $5,000
- Total Budgeted: $45,000
- Total Spent: $32,450
📁 Category Breakdown
| Category | Budgeted | Spent | Remaining |
|----------|----------|-------|-----------|
| Dining | $8,000 | $6,200 | $1,800 |
| Transportation | $3,000 | $2,100 | $900 |
| Groceries | $5,000 | $4,350 | $650 |
...
```
## New Features in v1.2.0
### Transfer Transactions
The `add_transaction` tool now supports the `transfer_to` parameter for creating transfers between accounts:
```json
{
"account": "Checking",
"amount": -100,
"transfer_to": "Savings",
"notes": "Monthly savings"
}
```
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:
```json
{
"account": "Checking",
"transactions": [
{
"date": "2024-01-01",
"amount": -50.00,
"payee_name": "Grocery Store",
"category": "Food",
"imported_id": "txn_001"
},
{
"date": "2024-01-02",
"amount": -100.00,
"payee_name": "Gas Station",
"category": "Transportation",
"imported_id": "txn_002"
}
]
}
```
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:
```json
// 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](https://actualbudget.org/)
- [Actual Budget API Documentation](https://actualbudget.org/docs/api/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
