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:

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

cp .env.example .env

Set transport to http in your .env:

ACTUAL_MCP_TRANSPORT=http

Start the server:

uv run -m actualbudgetpy.server

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.

Actual Budget MCP Server