Actual Budget MCP Server

A Model Context Protocol (MCP) server for Actual Budget. This server provides a suite of tools and resources for managing your personal finances directly via AI assistants that support MCP.

Features

Resources

• Account Listings (actual://accounts): View all your accounts with their balances.
• Categories (actual://categories): Access your full category structure.

Tools

• Account Management: get-accounts, get-transactions, balance-history
• Transaction Management: create-transaction, update-transaction
• Category Management: get-grouped-categories, create-category, update-category, delete-category, create-category-group, update-category-group, delete-category-group
• Payee Management: get-payees, create-payee, update-payee, delete-payee
• Rule Management: get-rules, create-rule, update-rule, delete-rule
• Analytics: spending-by-category, monthly-summary

Prompts

• Financial Insights: Generate analysis and recommendations.
• Budget Review: Analyze compliance and suggest adjustments.

Note: All monetary amounts use standard currency units (e.g., $12.34) rather than milliunits.

Prerequisites

• Node.js (v20+)
• An active Actual Budget instance

Setup

1. Install dependencies:

   npm install
   

2. Configure environment variables: Create a .env file in the root directory:

   # Required
   ACTUAL_DATA_DIR=/path/to/local-data-dir
   
   # Server connection
   ACTUAL_SERVER_URL=http://your-actual-server:5006
   ACTUAL_PASSWORD=your-password
   ACTUAL_BUDGET_ID=your-budget-id
   
   # Optional
   ACTUAL_ENCRYPTION_PASSWORD=your-encryption-password  # Required for encrypted budgets
   ACTUAL_AUTHORIZATION_HEADER=Bearer your-token        # For instances behind a reverse proxy
   DEBUG_LOGGING=true                                    # Enables verbose debug logging
   

   Logs are written to actual-mcp.log in the project root directory.

Build and Run

1. Build the project:

   npm run build
   

2. Run the server:

   npm run start
   

3. Development mode (no build required):

   npm run dev
   

Integrating with MCP Clients

Configure this MCP server in your AI assistant's configuration file. Both local (stdio) and remote (HTTP/SSE) configurations are supported.

Claude Desktop

Configuration file: ~/Library/Application Support/Claude/claude_desktop_config.json

Local (stdio):

{
  "mcpServers": {
    "actual-budget": {
      "command": "node",
      "args": ["/absolute/path/to/actual-mcp/dist/index.js"],
      "env": {
        "ACTUAL_SERVER_URL": "http://your-server:5006",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_BUDGET_ID": "your-budget-id",
        "ACTUAL_DATA_DIR": "/path/to/local-data-dir"
      }
    }
  }
}

Remote (HTTP):

{
  "mcpServers": {
    "actual-budget": {
      "httpUrl": "https://your-mcp-host.com/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token"
      },
      "timeout": 5000
    }
  }
}

Claude Code

Configuration file: ~/.claude/settings.json (global) or .claude/settings.json (project-level)

Local (stdio):

{
  "mcpServers": {
    "actual-budget": {
      "command": "node",
      "args": ["/absolute/path/to/actual-mcp/dist/index.js"],
      "env": {
        "ACTUAL_SERVER_URL": "http://your-server:5006",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_BUDGET_ID": "your-budget-id",
        "ACTUAL_DATA_DIR": "/path/to/local-data-dir"
      }
    }
  }
}

Remote (HTTP):

{
  "mcpServers": {
    "actual-budget": {
      "type": "http",
      "url": "https://your-mcp-host.com/mcp"
    }
  }
}

Gemini CLI

Configuration file: ~/.gemini/settings.json

Local (stdio):

{
  "mcpServers": {
    "actual-budget": {
      "command": "node",
      "args": ["/absolute/path/to/actual-mcp/dist/index.js"],
      "env": {
        "ACTUAL_SERVER_URL": "http://your-server:5006",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_BUDGET_ID": "your-budget-id",
        "ACTUAL_DATA_DIR": "/path/to/local-data-dir"
      },
      "timeout": 5000
    }
  }
}

Remote (HTTP):

{
  "mcpServers": {
    "actual-budget": {
      "httpUrl": "https://your-mcp-host.com/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token"
      },
      "timeout": 5000
    }
  }
}

Remote (SSE):

{
  "mcpServers": {
    "actual-budget": {
      "url": "https://your-mcp-host.com/sse",
      "headers": {
        "Authorization": "Bearer your-api-token"
      },
      "timeout": 5000
    }
  }
}

You can also use CLI commands:

gemini mcp add --transport http --header "Authorization: Bearer token" actual-budget https://your-host.com/mcp

OpenCode

Configuration file: ~/.config/opencode/opencode.jsonc

Local (stdio):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "actual-budget": {
      "type": "local",
      "command": ["node", "/absolute/path/to/actual-mcp/dist/index.js"],
      "environment": {
        "ACTUAL_SERVER_URL": "http://your-server:5006",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_BUDGET_ID": "your-budget-id",
        "ACTUAL_DATA_DIR": "/path/to/local-data-dir"
      },
      "enabled": true
    }
  }
}

Remote (HTTP):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "actual-budget": {
      "type": "remote",
      "url": "https://your-mcp-host.com/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token"
      },
      "enabled": true
    }
  }
}

For remote servers with OAuth, OpenCode handles authentication automatically. See OpenCode MCP docs for details.

Example Prompts for Testing

After configuring, try these prompts:

• "Show me my current account balances." (amounts shown as 123.45, not 12345000)
• "Get the last 10 transactions from my Checking account."
• "Give me financial insights for this month."
• "Review my current budget compliance."
• "Create a new payee called 'Grocery Store'"
• "Create a rule to categorize transactions from 'Netflix' as 'Entertainment'"

Docker

Build and run via Docker:

docker build -t actual-mcp .
docker run \
  -e ACTUAL_SERVER_URL=... \
  -e ACTUAL_PASSWORD=... \
  -e ACTUAL_BUDGET_ID=... \
  -e ACTUAL_DATA_DIR=/app/data \
  -v /host/path/to/data:/app/data \
  actual-mcp
# Add -e ACTUAL_AUTHORIZATION_HEADER="Bearer <token>" for instances behind a reverse proxy
# Add -e ACTUAL_ENCRYPTION_PASSWORD="..." for encrypted budgets

Troubleshooting

Logs

• Logs are written to actual-mcp.log in the project root
• Enable verbose debug logging: DEBUG_LOGGING=true in .env

Common Issues

Connection errors: Verify ACTUAL_SERVER_URL is reachable and ACTUAL_PASSWORD is correct.

Budget not found: Ensure ACTUAL_BUDGET_ID matches your budget ID in Actual.

Encrypted budgets: ACTUAL_ENCRYPTION_PASSWORD is required for budgets with end-to-end encryption enabled.

Amount format: All amounts use standard currency units (e.g., 12.34 for $12.34), not milliunits.

Testing

Run the test suite:

npm test