Skip to main content
Glama
actual-budget-mcp

actual-budget-mcp

Actual Budget MCP Server

An MCP server for Actual Budget built with FastMCP and actualpy.

Requirements

  • Python 3.11+

  • uv

  • A running Actual Budget server

Related MCP server: actual-mcp-server

Setup

git clone https://github.com/Saikumarmohan/actual-budget-mcp
cd actual-budget-mcp
uv sync

Configuration

All configuration is done via environment variables. Pass them via your MCP client config.

Variable

Required

Default

Description

ACTUAL_BASE_URL

✅

-

URL of your Actual Budget server

ACTUAL_PASSWORD

✅

-

Actual Budget server password

ACTUAL_FILE

✅

-

Budget file name or sync id

ACTUAL_CURRENCY

❌

USD

Currency code e.g. INR, EUR

ACTUAL_CURRENCY_SYMBOL

❌

$

Currency symbol e.g. ₹, €

ACTUAL_TIMEZONE

❌

UTC

Timezone e.g. Asia/Kolkata, America/New_York

ACTUAL_MCP_TRANSPORT

❌

stdio

Transport mode — stdio for Cline/Cursor, http for Docker

ACTUAL_MCP_HOST

❌

0.0.0.0

Host to bind to in HTTP mode

ACTUAL_MCP_PORT

❌

8000

Port to bind to in HTTP mode

MCP Client Config (Cline / Cursor)

Replace /path/to/actualbudgetpy with the absolute path to this project on your machine.

{
  "mcpServers": {
    "actualbudget": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/actualbudgetpy",
        "-m",
        "actualbudgetpy.server"
      ],
      "env": {
        "ACTUAL_BASE_URL": "http://localhost:5006",
        "ACTUAL_PASSWORD": "your_password",
        "ACTUAL_FILE": "your_file_id_or_name",
        "ACTUAL_CURRENCY": "USD",
        "ACTUAL_CURRENCY_SYMBOL": "$",
        "ACTUAL_TIMEZONE": "UTC"
      }
    }
  }
}

Note: On Windows, use the full path to uv.exe instead of just uv e.g. C:\\Users\\username\\.local\\bin\\uv.exe

HTTP Mode (Local)

For running as a standalone HTTP server locally:

  1. Copy .env.example to .env and fill in your values:

cp .env.example .env
  1. Set transport to http in your .env:

ACTUAL_MCP_TRANSPORT=http
  1. Start the server:

uv run -m actualbudgetpy.server
  1. Point your MCP client to http://localhost:8000/mcp:

{
  "mcpServers": {
    "actualbudget": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Docker

# build
docker build -t actualbudgetpy .

# run
docker run -p 8000:8000 \
  -e ACTUAL_BASE_URL=http://your-server:5006 \
  -e ACTUAL_PASSWORD=your_password \
  -e ACTUAL_FILE=your_file_id \
  -e ACTUAL_CURRENCY=USD \
  -e ACTUAL_CURRENCY_SYMBOL=$ \
  -e ACTUAL_TIMEZONE=UTC \
  actualbudgetpy

Then point your MCP client to http://localhost:8000/mcp.

Available Tools

Read

Tool

Description

list_accounts

List all accounts

list_payees

List all payees

list_transactions

List transactions with optional filters — date, account, category, payee, notes

list_categories

List all categories, filterable by income or expense

list_category_groups

List all category groups

list_budgets

List budget allocations by month

Write

Tool

Description

add_transaction

Create a new transaction

update_transaction

Update an existing transaction

delete_transaction

Delete a transaction by id

create_transfer

Transfer money between two accounts

set_budget

Set budget amount for a category in a month

Resources

Resources are read-only data the AI can attach as context at the start of a conversation.

Resource

Description

budget://accounts

Live list of all accounts

budget://categories

Live list of all categories

Prompts

Reusable prompt templates that guide the AI through common workflows.

Prompt

Parameters

Description

monthly_review

month (YYYY-MM)

Full budget vs spending analysis for a month

spending_by_category

category, start_date, end_date

Spending breakdown for a specific category

add_expense

description

Natural language guided expense entry

Author

Built by Saikumar — feel free to connect!

If you find this useful, consider giving it a ⭐ on GitHub.

Available Tools

11 tools
add_transactionA

Create a new transaction in Actual Budget. date must be in YYYY-MM-DD format. amount is in dollars — use negative for expenses, positive for income. Use list_accounts for account names, list_payees for payee names, list_categories for category names. Returns the created transaction id and details.

Inputs: date (required), amount (required), account (required), notes, +3 more. Returns: object

create_transferA

Transfer money between two accounts in Actual Budget. amount must be positive — direction is determined by from_account and to_account. Use list_accounts to get account names. Returns both the debit and credit transaction details.

Inputs: date (required), amount (required), to_account (required), from_account (required), +1 more. Returns: object

delete_transactionA
Destructive

Delete a transaction from Actual Budget by id. This is destructive and cannot be undone. Use list_transactions to get transaction ids. Returns the id of the deleted transaction.

Inputs: transaction_id (required). Returns: object

list_accountsA

List all accounts from Actual Budget. Returns each account's id, name, whether it is off-budget, and whether it is closed. Use this to get account ids needed for filtering transactions.

Inputs: no named parameters. Returns: result

list_budgetsA

List budget allocations from Actual Budget. month must be in YYYY-MM-DD format (e.g. 2024-01-01 for January 2024). If month is not provided, returns budgets for all months. Returns category name, budgeted amount, and month. Use list_categories to get category names.

Inputs: month. Returns: result

list_categoriesA

List all budget categories from Actual Budget. Optionally filter by is_income=True for income categories or is_income=False for expense categories. Returns category id, name, group name, and whether it is an income category. Use category names when filtering transactions by category.

Inputs: is_income. Returns: result

list_category_groupsA

List all category groups from Actual Budget. Returns group id, name, and whether it is an income group. Use this to understand how categories are organised.

Inputs: no named parameters. Returns: result

list_payeesA

List all payees from Actual Budget. Returns each payee's id and name. Use payee names when filtering transactions by payee.

Inputs: no named parameters. Returns: result

list_transactionsA

List transactions from Actual Budget with optional filters. Dates must be in YYYY-MM-DD format. account, category and payee accept names or ids. notes accepts a partial string to search within transaction notes. Returns date, account, payee, category, notes, and amount (in USD). Use list_accounts to get account names, list_categories for category names, list_payees for payee names.

Inputs: notes, payee, account, category, +2 more. Returns: result

set_budgetA

Set the budget amount for a category in a given month in Actual Budget. month must be in YYYY-MM-DD format e.g. 2024-01-01 for January 2024. Use list_categories to get category names. Returns the updated budget details.

Inputs: month (required), amount (required), category (required). Returns: object

update_transactionA

Update an existing transaction in Actual Budget. Only provided fields will be updated, others remain unchanged. Use list_transactions to get transaction ids. Returns the updated transaction details.

Inputs: transaction_id (required), date, notes, payee, +3 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool targets a distinct entity or action: listing accounts, payees, transactions, categories, category groups, and budgets are clearly separated, while add/update/delete transaction, create_transfer, and set_budget each address a unique mutation. No two tools appear to overlap in purpose.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern: list_* for retrieval, add/update/delete for transaction mutations, create_transfer for transfers, and set_budget for budget setting. The convention is uniform and predictable.

    Tool Count5/5

    With 11 tools, the server is well-scoped for interacting with Actual Budget. Each tool serves a clear purpose without redundancy, and the count is within the ideal 3-15 range for a domain-specific MCP server.

    Completeness5/5

    The tool surface covers the core lifecycle for transactions (list, add, update, delete, transfer) and budgets (list, set), plus all necessary reference listings (accounts, payees, categories, category groups). There are no obvious dead ends for typical budget management workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      MCP server for integrating Actual Budget with Claude and other LLM assistants.
      17
      386 npm
      293
      TypeScript
      MIT
    • A
      license
      A
      quality
      A
      maintenance
      Lets AI assistants read and manage a self-hosted Actual Budget: accounts, transactions, budgets, categories, payees, rules, schedules and reports. Runs over stdio for Claude Desktop and Claude Code, or over HTTP with Bearer or OIDC auth for LibreChat and LobeChat.
      15
      2,787 npm
      80
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Bridges AI/LLM applications to Actual Budget, exposing budget data as MCP tools for account listing, transactions, and budget balances.
      4
      -
    • A
      license
      B
      quality
      A
      maintenance
      An MCP server that connects Actual Budget to Claude, enabling users to manage budgets, transactions, and spending insights through natural language.
      37
      263 npm
      20
      MIT