Skip to main content
Glama

actual-mcp

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

Transaction & Account Management
  • get-transactions - Retrieve and filter transactions by account, date, amount, category, or payee
  • get-accounts - Retrieve a list of all accounts with their current balance and ID
  • balance-history - View account balance changes over time
Reporting & Analytics
  • spending-by-category - Generate spending breakdowns categorized by type
  • monthly-summary - Get monthly income, expenses, and savings metrics
Categories
  • 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
Payees
  • 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
Rules
  • 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

Prompts

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

Installation

Prerequisites

Remote access

Pull the latest docker image:

docker pull sstefanov/actual-mcp:latest

Local setup

  1. Clone the repository:
git clone https://github.com/sstefanov/actual-mcp.git cd actual-mcp
  1. Install dependencies:
npm install
  1. Build the server:
npm run build
  1. Build the local docker image (optional):
docker build -t <local-image-name> .
  1. 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"

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

a. Using Node.js (npx version):

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

b. Using Docker (local or remote images):

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

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.

Running an SSE Server

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" \ sstefanov/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.

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.

Related MCP Servers

  • -
    security
    A
    license
    -
    quality
    An MCP server that allows accessing and managing ledger files through Claude by providing account listing, balance checking, and transaction register viewing capabilities.
    Last updated -
    3
    GPL 3.0
    • Apple
  • -
    security
    A
    license
    -
    quality
    AI-powered MCP server that enables Claude and other LLMs to interact directly with construction documents, drawings, and specifications through advanced RAG and hybrid search capabilities.
    Last updated -
    3
    MIT License
  • -
    security
    F
    license
    -
    quality
    An MCP server that allows Claude to interact with local LLMs running in LM Studio, providing access to list models, generate text, and use chat completions through local models.
    Last updated -
    10
  • -
    security
    F
    license
    -
    quality
    A simple MCP server that provides a calculator tool, dynamic greeting resources, and code review prompts, demonstrating how to build standardized interfaces for LLM applications.
    Last updated -

View all related MCP servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/s-stefanov/actual-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server