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

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).

• 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

• get-transactions - Retrieve and filter transactions by account, date, amount, category, or payee
• create-transaction - Create a new transaction in an account with optional category, payee, and notes
• update-transaction - Update an existing transaction with new category, payee, notes, or amount
• get-accounts - Retrieve a list of all accounts with their current balance and ID
• balance-history - View account balance changes over time

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

• get-grouped-categories - Retrieve a list of all category groups with their categories
• create-category - Create a new category within a category group
• update-category - Update an existing category's name or group
• delete-category - Delete a category
• create-category-group - Create a new category group
• update-category-group - Update a category group's name
• delete-category-group - Delete a category group

• 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

• 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

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

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

Pull the latest docker image from GitHub Container Registry:

docker pull ghcr.io/baruchiro/actual-mcp:latest

For PR preview images (replace 123 with PR number):

docker pull ghcr.io/baruchiro/actual-mcp:pr-123

1. Clone the repository:

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

2. Install dependencies:

npm install

3. Build the server:

npm run build

4. Build the local docker image (optional):

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

5. 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"

Optional: separate encryption budget password

If your Actual setup requires a different password to unlock the local/encrypted budget data than the server authentication password, you can set ACTUAL_BUDGET_ENCRYPTION_PASSWORD in addition to ACTUAL_PASSWORD.

# If server auth and encryption/unlock use different passwords
export ACTUAL_BUDGET_ENCRYPTION_PASSWORD="your-encryption-password"

Optional: currency symbol

Actual Budget is currency-agnostic. By default, formatted amounts are shown without a currency symbol (e.g., 1,234.56). If you want to display amounts with currency formatting, you can set ACTUAL_MCP_CURRENCY_SYMBOL to a valid ISO 4217 currency code:

# Choose one of the following currency codes:
export ACTUAL_MCP_CURRENCY_SYMBOL="USD"  # For US Dollars: $1,234.56
# export ACTUAL_MCP_CURRENCY_SYMBOL="EUR"  # For Euros: €1,234.56
# export ACTUAL_MCP_CURRENCY_SYMBOL="GBP"  # For British Pounds: £1,234.56

Optional: budget cache TTL

By default the server keeps the downloaded budget cached in memory for 60 seconds between tool calls instead of re-downloading it every time, which makes back-to-back requests much faster. Cached data is kept current by syncing the latest changes from your Actual server on each reuse, so you still see up-to-date data. Tune or disable it with ACTUAL_MCP_CACHE_TTL_SECONDS:

export ACTUAL_MCP_CACHE_TTL_SECONDS="120"  # keep the budget warm for 2 minutes
# export ACTUAL_MCP_CACHE_TTL_SECONDS="0"  # disable caching (re-download every call)

Optional: pin the @actual-app/api version (Docker)

The Docker image ships with a specific @actual-app/api version, but different self-hosted Actual deployments run different sync-server versions, and the bundled API does not always match yours. Set ACTUAL_MCP_API_VERSION to have the container install a matching version at startup, without rebuilding the image:

# Install an exact version that matches your sync-server (recommended)
export ACTUAL_MCP_API_VERSION="26.5.2"
# export ACTUAL_MCP_API_VERSION="latest"  # always install the newest published version

• Unset (default): use the version baked into the image — no extra startup cost. This is the only mode that works offline / without npm access.
• An exact version: runs npm install @actual-app/api@<version> before launching. Skipped if that version is already installed.
• latest: installs the newest published version on every start.

💡 This adds ~npm-install time to container startup and only applies to the Docker image (the entrypoint runs the install). If the install fails, the container exits non-zero so your Docker restart policy can react.

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...

{
  "mcpServers": {
    "actualBudget": {
      "command": "npx",
      "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"
      }
    }
  }
}

{
  "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",
        "ghcr.io/baruchiro/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.

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" \
  ghcr.io/baruchiro/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.

Docker images are published to GitHub Container Registry (ghcr.io) with the following tags:

• latest - Latest release from the main branch
• v1.2.3 - Specific version tags (e.g., v1.8.0)
• 1.2.3, 1.2, 1 - Semantic version aliases
• pr-123 - Preview images for pull requests (e.g., pr-42 for PR #42)

To test a pull request before it's merged, you can use the PR-specific Docker image:

# Replace 123 with the actual PR number
docker pull ghcr.io/baruchiro/actual-mcp:pr-123

# Run the PR preview
docker run -i --rm \
  -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" \
  ghcr.io/baruchiro/actual-mcp:pr-123 \
  --enable-write

This allows you to test new features or bug fixes before they are officially released.

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"

Example Codex configuration:

In ~/.codex/config.toml:

[mcp_servers.actual-budget]
url = "http://localhost:3000"

Point Codex at the same port you pass to npm start -- --sse --port <PORT>.

For development with auto-rebuild:

npm run watch

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

node build/index.js --test-resources

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

npx @modelcontextprotocol/inspector node build/index.js

• 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

MIT

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