Actual Budget

This MCP server lets Claude interact with your Actual Budget data to record transactions, query balances, track budgets, search transactions, and analyze spending. It connects your budgeting setup to natural language conversations so you can manage finances smoothly with AI.

How to use

You connect Claude to the MCP endpoint and then tell Claude what you want to do with your Actual Budget data. Typical tasks include: creating transactions (income or expense), checking balances for accounts, viewing monthly budget status, searching past transactions by merchant or notes, and generating spending analyses. Claude will respond with confirmations, current balances, and budget summaries based on your configured data.

How to install

Prerequisites you need before installation are a running Actual Budget server, password authentication (OpenID users should also enable password login), and Docker for deployment.

cp .env.example .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

1. Build and run the MCP image with Docker. 2) Or use Docker Compose to start the service in the background.

# Build the image
docker build -t actual-budget-mcp .

# Run the container
docker run -d \
  --name actual-budget-mcp \
  -p 3000:3000 \
  --env-file .env \
  actual-budget-mcp

# Or start with Docker Compose
docker-compose up -d

Connect Claude to MCP

In Claude, set up an MCP Connector to point to your server. The MCP endpoint is where Claude will send requests and receive responses.

Steps to connect:

• Open Claude settings and navigate to Connectors.

• Add a new Connector and choose MCP.

• Enter the MCP URL: http://your-server:3000/mcp

Local development and alternatives

If you prefer running locally instead of Docker, you can install dependencies and start the MCP client directly. Ensure you have Node.js installed.

# Install dependencies
npm install

# Development mode (requires a .env file)
npm run dev

# Build for production
npm run build

# Start the MCP server locally
npm start

Configuration and security notes

Create a .env file from the template and provide essential values for your environment. Keep your password and budget IDs secure.

Environment variables to set (as shown): ACTUAL_SERVER_URL, ACTUAL_PASSWORD, ACTUAL_BUDGET_ID. If you enable end-to-end encryption, also set ACTUAL_ENCRYPTION_PASSWORD.

Troubleshooting

Connection issues: Make sure the Actual Budget server is running and the ACTUAL_SERVER_URL is correct. If using Docker networking, verify container names and network access.

Authentication issues: Confirm the password is correct. If you use OpenID, ensure password login is enabled in your authentication config.

Budget lookup issues: Ensure ACTUAL_BUDGET_ID is the correct Sync ID from your Budget settings.

Encryption errors: If end-to-end encryption is enabled, provide ACTUAL_ENCRYPTION_PASSWORD.

Endpoints and tooling

Endpoints expose the MCP interface for budget operations. Tools available through the MCP include actions to get accounts, query balances, add transactions, fetch transaction histories, search transactions, manage categories, budgets, payees, and spending summaries.

Available tools

get_accounts

Retrieve all accounts and balances.

get_account_balance

Query the balance of a specific account.

add_transaction

Add a new transaction (income or expense) to an account.

get_transactions

Fetch transaction history for an account.

search_transactions

Search transactions by recipient, notes, or amount.

get_categories

Retrieve all budget categories.

get_budget_month

View the monthly budget overview.

set_budget_amount

Set the budget amount for a category.

get_payees

Retrieve all payees/vendors.

get_spending_summary

Get a spending summary analysis.

sync_budget

Synchronize budget data.