Actual Budget MCP Server

How to use

Use an MCP-compatible client to connect to the Actual Budget MCP Server. You can run the server locally via a Node-based setup or via Docker and then point your client to the provided MCP endpoint. Once connected, you can query accounts, view transaction history, generate spending insights, manage categories, payees, and rules, and receive actionable financial insights in natural language.

Two explicit local runtime options are shown for starting the MCP server. The first uses a Node-based runtime via npx and enables write access. The second runs the server in Docker and also enables write access. In both cases you supply the necessary environment values for your Actual Budget data and server endpoint.

How to install

Prerequisites you need before starting the server:

• 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 with this command.

docker pull sstefanov/actual-mcp:latest

Local setup steps (option 1: Node-based run): clone the project, install dependencies, and build the server.

git clone https://github.com/s-stefanov/actual-mcp.git
cd actual-mcp
npm install
npm run build

Optionally build a local Docker image from your clone (if you prefer running locally with Docker):

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

Configure environment variables for your Actual Budget data and server settings. Replace placeholders with your actual values.

# 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 setup requires unlocking local data with a different password than server authentication.

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

Additional configuration and usage notes

Usage with Claude Desktop lets you connect the Actual Budget MCP Server by adding a server configuration to the Claude setup. You can choose either a Node.js runtime via npx or a Docker-based runtime. Both require you to provide environment values that point to your Actual Budget data and server URL.

Here are the explicit runtime configurations shown for Claude Desktop. Use the exact blocks in your Claude setup to enable write access and connect to your data.

{
  "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"
      }
    }
  }
}

{
  "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",
        "sstefanov/actual-mcp:latest",
        "--enable-write"
      ]
    }
  }
}

Security and access notes

If you plan to expose the MCP server publicly, enable secure access where available and provide a bearer token. When you use the Bearer token option, ensure the BEARER_TOKEN environment variable is set in your runtime configuration.

Keep your Actual Budget credentials and data paths secure. Do not share your data directory paths or passwords in public configurations.

Prompts and insights

The MCP server supports prompts that generate financial insights and budget reviews. Use these prompts to get actionable recommendations based on your data, such as spending patterns by category or adjustments to improve budget compliance.

Troubleshooting and tips

If you have trouble connecting, verify that all environment variables are correctly set and that the server process has access to your Actual Budget data. Use the MCP Inspector tool if you need to debug the protocol interaction.

For development and testing, you can verify the connection with a quick test resource run that checks the server’s ability to access Actual Budget data.

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 budget compliance and suggest adjustments