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

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

2. Set transport to http in your .env:

ACTUAL_MCP_TRANSPORT=http

3. Start the server:

uv run -m actualbudgetpy.server

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