
Model Context Protocol for Actual Budget API
Model Context Protocol for Actual Budget API
·
MCP server for integrating Actual Budget with Claude and other LLM assistants.
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).
get-transactions - Retrieve and filter transactions by account, date, amount, category, or payeecreate-transaction - Create a new transaction in an account with optional category, payee, and notesupdate-transaction - Update an existing transaction with new category, payee, notes, or amountget-accounts - Retrieve a list of all accounts with their current balance and IDbalance-history - View account balance changes over timespending-by-category - Generate spending breakdowns categorized by typemonthly-summary - Get monthly income, expenses, and savings metricsbudget-vs-actual - Compare budgeted amounts against actual spending per categorynet-worth - Track assets, liabilities, and net worth across all accounts over timecategory-trends - See how spending in each category moves month over month, with trend directionspending-by-payee - Rank payees by how much was spent with (or received from) each onecash-flow - Report income, expenses, and net cash flow per month or weekThe five tools above return JSON rather than markdown, so amounts stay machine-readable. Every amount is an integer number of cents, and each response carries an
amountsInfield describing the sign conventions it uses.
get-custom-reports - Retrieve every saved custom report from the Reports sectioncreate-custom-report - Create a saved custom reportupdate-custom-report - Update fields on a saved custom report, leaving the rest unchangeddelete-custom-report - Delete a saved custom reportget-dashboards - Retrieve every dashboard page and the widgets laid out on itadd-dashboard-widget - Add a widget to a dashboard pageupdate-dashboard-widget - Update a widget's configuration, position, or sizeremove-dashboard-widget - Remove a widget from its pageorganize-dashboard - Reposition and resize several widgets at oncecreate-dashboard-page / rename-dashboard-page / delete-dashboard-page - Manage dashboard pagesget-grouped-categories - Retrieve a list of all category groups with their categoriescreate-category - Create a new category within a category groupupdate-category - Update an existing category's name or groupdelete-category - Delete a categorycreate-category-group - Create a new category groupupdate-category-group - Update a category group's namedelete-category-group - Delete a category groupget-payees - Retrieve a list of all payees with their detailscreate-payee - Create a new payeeupdate-payee - Update an existing payee's detailsdelete-payee - Delete a payeemerge-payees - Merge duplicate payees into a single target payeeget-rules - Retrieve a list of all transaction rulescreate-rule - Create a new transaction rule with conditions and actionsupdate-rule - Update an existing transaction ruledelete-rule - Delete a transaction rulefinancial-insights - Generate insights and recommendations based on your financial databudget-review - Analyze your budget compliance and suggest adjustmentsPull the latest docker image:
docker pull sstefanov/actual-mcp:latestgit clone https://github.com/s-stefanov/actual-mcp.git
cd actual-mcpnpm installnpm run builddocker build -t <local-image-name> .# 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"
# How long downloaded data stays fresh before the server re-syncs, in ms
# (default: 60000). Use 0 to sync before every call, or -1 to never sync.
export ACTUAL_SYNC_TTL_MS="60000"Optional: separate encryption budget password
If your Actual setup requires a different password to unlock the local/encrypted budget data than the server authentication password, you can set ACTUAL_BUDGET_ENCRYPTION_PASSWORD in addition to ACTUAL_PASSWORD.
# If server auth and encryption/unlock use different passwords
export ACTUAL_BUDGET_ENCRYPTION_PASSWORD="your-encryption-password"Optional: OpenID servers (session token auth)
If your Actual server uses OpenID login (for example Google) with ACTUAL_OPENID_ENFORCE=true, password login is disabled, so ACTUAL_PASSWORD can't be used. Instead, sign in to Actual in a browser and pass the resulting session token. It takes precedence over ACTUAL_PASSWORD.
export ACTUAL_SERVER_URL="https://your-actual-server.com"
export ACTUAL_SESSION_TOKEN="your-session-token"To find the token, sign in to Actual in your browser, open DevTools, and go to Application → IndexedDB → actual → asyncStorage. The value of the user-token key is your session token. It's a UUID (e.g. 3f2b8c1e-9a4d-4e7b-8c2a-1d5e6f7a8b9c), not a long JWT-style bearer token. You can check it with curl -H "X-ACTUAL-TOKEN: <token>" https://your-actual-server.com/account/validate, which should return "validated": true. Treat it like a password: it grants full access to your budgets. How long it stays valid depends on the server's ACTUAL_TOKEN_EXPIRATION setting. If it is invalid or expired, the MCP server still starts, but tool calls fail with Authentication failed: invalid or expired session token, because the server connects to Actual on the first request (--test-resources reports the error immediately). Sign in again, replace the token, and restart the MCP server.
The server keeps one shared Actual connection for its entire lifetime and serializes budget operations through it. Downloaded data is re-synced when it exceeds the ACTUAL_SYNC_TTL_MS freshness window. In both stdio and HTTP modes, SIGINT and SIGTERM drain in-flight work before the server shuts down. Actual is no longer initialized and shut down for each tool call.
To use this server with Claude Desktop, add it to your Claude configuration:
On MacOS:
code ~/Library/Application\ Support/Claude/claude_desktop_config.jsonOn Windows:
code %APPDATA%\Claude\claude_desktop_config.jsonAdd the following to your configuration...
{
"mcpServers": {
"actualBudget": {
"command": "npx",
"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"
}
}
}
}{
"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_DIRis optional if you're usingACTUAL_SERVER_URL.
💡 Use
--enable-writeto enable write-access tools.
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.
Once connected, you can ask Claude questions like:
Example Codex configuration:
In ~/.codex/config.toml:
[mcp_servers.actual-budget]
url = "http://localhost:3000"Point Codex at the same port you pass to npm start -- --sse --port <PORT>.
For development with auto-rebuild:
npm run watchTo verify the server can connect to your Actual Budget data:
node build/index.js --test-resourcesSince MCP servers communicate over stdio, debugging can be challenging. You can use the MCP Inspector:
npx @modelcontextprotocol/inspector node build/index.jsThe end-to-end test suite (vitest.e2e.config.ts) spins up a real Actual Budget server in a Docker container (via Testcontainers), seeds a budget, and drives it through a real MCP client over stdio to verify accounts, transactions, categories, payees, rules, and imports actually persist. It requires Docker to be running locally.
In CI, the e2e-test job in .github/workflows/pr-validation.yml only runs on release-please PRs (branch prefix release-please--) or when a PR is given the run-e2e label — it does not run on every PR by default, since it needs Docker and takes longer than the standard checks.
To run it locally:
npm run build && npm run test:e2eDocker must be installed and running; the test suite pulls and starts the Actual server image automatically.
index.ts - Main server implementationtypes.ts - Type definitions for API responses and parametersprompts.ts - Prompt templates for LLM interactionsutils.ts - Helper functions for date formatting and moreactual-mcp is published to the official MCP Registry
as io.github.s-stefanov/actual-mcp. Registry metadata lives in
server.json and is published automatically on each release
(see .github/workflows/release-please.yml).
It advertises two transports on the npm package — stdio (default) and
streamable-http (via the --sse flag). (A Docker image is also published,
but is not yet listed as a registry package.)
Post-release directory listings are tracked in
docs/mcp-registry-checklist.md.
MIT
Contributions are welcome! Please feel free to submit a Pull Request.
This repo does not document an install step we could read. Check the README on GitHub.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/actual-budget-mcp-server to learn what the "Actual Budget MCP Server" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
This server doesn't publish a machine-readable tool manifest, and it doesn't expose a public endpoint we could ask. Connect the server locally to see what it exposes.
We could not run this server: it ships no npx package for our sandbox and no public endpoint. The four checks that need a live server are left out, and the grade tops out at B until one exists.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/actual-budget-mcp-server)Nothing comparable is listed yet.
v1.15.1Release notesv1.15.0Release notesv1.14.0Release notesv1.13.0Release notesv1.12.1Release notesv1.12.0Release notesv1.11.3Release notesv1.11.2Release notesv1.11.1Release notesv1.11.0Release notesv1.10.0Release notesv1.9.0Release notesv1.8.0Release notesv1.7.0Release notesv1.6.0Release notesv1.5.0Release notesv1.4.0Release notesv1.3.0Release notesv1.2.2Release notesv1.2.1Release notesConnect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "actual-budget-mcp-server" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.