What is Actual Mcp

actual-mcp is a Model Context Protocol server designed to integrate Actual Budget with Claude and other LLM assistants, allowing users to interact with their personal financial data using natural language.

Use cases

Use cases include retrieving transaction data, analyzing spending habits, generating monthly financial summaries, and providing personalized financial insights and budget reviews.

How to use

To use actual-mcp, clone the repository, install the necessary dependencies, build the server, and configure the environment variables as needed. Ensure you have Actual Budget and a compatible LLM client like Claude Desktop.

Key features

Key features include account listings, detailed account information, transaction history access, tools for retrieving and filtering transactions, generating spending breakdowns, monthly summaries, and financial insights.

Where to use

actual-mcp can be used in personal finance management, budgeting applications, and any context where users need to analyze and manage their financial data effectively.

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

• 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

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:

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

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

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"

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.