Actual Budget MCP Server

MCP server for integrating Actual Budget with Claude and other LLM assistants.

Overview

The Actual Budget MCP Server allows you to interact with your personal financial data from Actual Budget using natural language through LLMs. It exposes your accounts, transactions, and financial metrics through the Model Context Protocol (MCP).

Features

Resources

Account Listings - Browse all your accounts with their balances
Account Details - View detailed information about specific accounts
Transaction History - Access transaction data with complete details

Tools

Transaction & Account Management

get-transactions - Retrieve and filter transactions by account, date, amount, category, or payee
get-accounts - Retrieve a list of all accounts with their current balance and ID
balance-history - View account balance changes over time

Reporting & Analytics

spending-by-category - Generate spending breakdowns categorized by type
monthly-summary - Get monthly income, expenses, and savings metrics

Payees

get-payees - Retrieve a list of all payees with their details
create-payee - Create a new payee
update-payee - Update an existing payee's details
delete-payee - Delete a payee

Rules

get-rules - Retrieve a list of all transaction rules
create-rule - Create a new transaction rule with conditions and actions
update-rule - Update an existing transaction rule
delete-rule - Delete a transaction rule

Prompts

financial-insights - Generate insights and recommendations based on your financial data
budget-review - Analyze your budget compliance and suggest adjustments

Installation

Prerequisites

Node.js (v16 or higher)
Actual Budget installed and configured
Claude Desktop or another MCP-compatible client
Docker Desktop (optional)

Remote access

Pull the latest docker image:

docker pull sstefanov/actual-mcp:latest

Local setup

Clone the repository:

git clone https://github.com/sstefanov/actual-mcp.git
cd actual-mcp

Install dependencies:

npm install

Build the server:

npm run build

Build the local docker image (optional):

docker build -t <local-image-name> .

Configure environment variables (optional):

# Path to your Actual Budget data directory (default: ~/.actual)
export ACTUAL_DATA_DIR="/path/to/your/actual/data"

# If using a remote Actual server
export ACTUAL_SERVER_URL="https://your-actual-server.com"
export ACTUAL_PASSWORD="your-password"

# Specific budget to use (optional)
export ACTUAL_BUDGET_SYNC_ID="your-budget-id"

Usage with Claude Desktop

To use this server with Claude Desktop, add it to your Claude configuration:

On MacOS:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

On Windows:

code %APPDATA%\Claude\claude_desktop_config.json

Add the following to your configuration...

a. Using Node.js (npx version):

{
  "mcpServers": {
    "actualBudget": {
      "command": "node",
      "args": ["-y", "actual-mcp", "--enable-write"],
      "env": {
        "ACTUAL_DATA_DIR": "path/to/your/data",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_SERVER_URL": "http://your-actual-server.com",
        "ACTUAL_BUDGET_SYNC_ID": "your-budget-id"
      }
    }
  }
}

### a. Using Node.js (local only):

```json
{
  "mcpServers": {
    "actualBudget": {
      "command": "node",
      "args": ["/path/to/your/clone/build/index.js", "--enable-write"],
      "env": {
        "ACTUAL_DATA_DIR": "path/to/your/data",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_SERVER_URL": "http://your-actual-server.com",
        "ACTUAL_BUDGET_SYNC_ID": "your-budget-id"
      }
    }
  }
}

b. Using Docker (local or remote images):

{
  "mcpServers": {
    "actualBudget": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/data:/data",
        "-e",
        "ACTUAL_PASSWORD=your-password",
        "-e",
        "ACTUAL_SERVER_URL=https://your-actual-server.com",
        "-e",
        "ACTUAL_BUDGET_SYNC_ID=your-budget-id",
        "sstefanov/actual-mcp:latest",
        "--enable-write"
      ]
    }
  }
}

After saving the configuration, restart Claude Desktop.

💡 ACTUAL_DATA_DIR is optional if you're using ACTUAL_SERVER_URL.

💡 Use --enable-write to enable write-access tools.

Running an SSE Server

To expose the server over a port using Docker:

docker run -i --rm \
  -p 3000:3000 \
  -v "/path/to/your/data:/data" \
  -e ACTUAL_PASSWORD="your-password" \
  -e ACTUAL_SERVER_URL="http://your-actual-server.com" \
  -e ACTUAL_BUDGET_SYNC_ID="your-budget-id" \
  -e BEARER_TOKEN="your-bearer-token" \
  sstefanov/actual-mcp:latest \
  --sse --enable-write --enable-bearer

⚠️ Important: When using --enable-bearer, the BEARER_TOKEN environment variable must be set.
🔒 This is highly recommended if you're exposing your server via a public URL.

Example Queries

Once connected, you can ask Claude questions like:

"What's my current account balance?"
"Show me my spending by category last month"
"How much did I spend on groceries in January?"
"What's my savings rate over the past 3 months?"
"Analyze my budget and suggest areas to improve"

Development

For development with auto-rebuild:

npm run watch

Testing the connection to Actual

To verify the server can connect to your Actual Budget data:

node build/index.js --test-resources

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. You can use the MCP Inspector:

npx @modelcontextprotocol/inspector node build/index.js

Project Structure

index.ts - Main server implementation
types.ts - Type definitions for API responses and parameters
prompts.ts - Prompt templates for LLM interactions
utils.ts - Helper functions for date formatting and more

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Actual Budget