Actual Budget MCP server

The Actual Budget MCP Server enables interaction with your Actual Budget financial data through LLMs using natural language. It connects your accounts, transactions, and financial metrics via the Model Context Protocol (MCP), allowing AI assistants like Claude to analyze and provide insights on your finances.

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

• get-transactions - Retrieve and filter transactions by account, date, amount, category, or payee
• spending-by-category - Generate spending breakdowns categorized by type
• monthly-summary - Get monthly income, expenses, and savings metrics
• balance-history - View account balance changes over time

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

Setup

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

Using 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

Configuration Options

Using npx:

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

Using Docker:

{
  "mcpServers": {
    "actualBudget": {
      "command": "docker",
      "args": ["run", "-it", "--rm", "-p", "3000:3000", "sstefanov/actual-mcp:latest"],
      "env": {
        "ACTUAL_DATA_DIR": "/path/to/your/actual/data",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_SERVER_URL": "https://your-actual-server.com",
        "ACTUAL_BUDGET_SYNC_ID": "your-budget-id"
      }
    }
  }
}

After saving the configuration, restart Claude Desktop.

Testing the Connection

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

node build/index.js --test-resources

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"

Debugging

Since MCP servers communicate over stdio, you can use the MCP Inspector for debugging:

npx @modelcontextprotocol/inspector node build/index.js

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "actualBudget" '{"command":"npx","args":["-y","actual-mcp"],"env":{"ACTUAL_DATA_DIR":"/path/to/your/actual/data","ACTUAL_PASSWORD":"your-password","ACTUAL_SERVER_URL":"https://your-actual-server.com","ACTUAL_BUDGET_SYNC_ID":"your-budget-id"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect