actual-budget-mcp
Provides tools for interacting with Actual Budget, enabling AI agents to manage accounts, payees, transactions, categories, budgets, and transfers.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@actual-budget-mcp Show my spending by category this month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Actual Budget MCP Server
An MCP server for Actual Budget built with FastMCP and actualpy.
Requirements
Python 3.11+
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 syncConfiguration
All configuration is done via environment variables. Pass them via your MCP client config.
Variable | Required | Default | Description |
| ✅ | - | URL of your Actual Budget server |
| ✅ | - | Actual Budget server password |
| ✅ | - | Budget file name or sync id |
| ❌ |
| Currency code e.g. |
| ❌ |
| Currency symbol e.g. |
| ❌ |
| Timezone e.g. |
| ❌ |
| Transport mode — |
| ❌ |
| Host to bind to in HTTP mode |
| ❌ |
| 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.exeinstead of justuve.g.C:\\Users\\username\\.local\\bin\\uv.exe
HTTP Mode (Local)
For running as a standalone HTTP server locally:
Copy
.env.exampleto.envand fill in your values:
cp .env.example .envSet transport to
httpin your.env:
ACTUAL_MCP_TRANSPORT=httpStart the server:
uv run -m actualbudgetpy.serverPoint 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 \
actualbudgetpyThen point your MCP client to http://localhost:8000/mcp.
Available Tools
Read
Tool | Description |
| List all accounts |
| List all payees |
| List transactions with optional filters — date, account, category, payee, notes |
| List all categories, filterable by income or expense |
| List all category groups |
| List budget allocations by month |
Write
Tool | Description |
| Create a new transaction |
| Update an existing transaction |
| Delete a transaction by id |
| Transfer money between two accounts |
| 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 |
| Live list of all accounts |
| Live list of all categories |
Prompts
Reusable prompt templates that guide the AI through common workflows.
Prompt | Parameters | Description |
|
| Full budget vs spending analysis for a month |
|
| Spending breakdown for a specific category |
|
| 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 toolsadd_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_transactionADestructive
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
Scored across 11 tools
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.
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.
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.
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
Related MCP Connectors
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
Read-only finance MCP server. Connects your banks, cards, payment apps, books and payroll into one ledger for your AI. Can't move money. Open source (AGPL-3.0), free during beta.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Related MCP Servers
- AlicenseBqualityBmaintenanceMCP server for integrating Actual Budget with Claude and other LLM assistants.17386 npm293TypeScriptMIT
- AlicenseAqualityAmaintenanceLets 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.152,787 npm80MIT
- FlicenseAqualityDmaintenanceBridges AI/LLM applications to Actual Budget, exposing budget data as MCP tools for account listing, transactions, and budget balances.4-
- AlicenseBqualityAmaintenanceAn MCP server that connects Actual Budget to Claude, enabling users to manage budgets, transactions, and spending insights through natural language.37263 npm20MIT