Actual Budget
About
Integrate Actual Budget with LLM assistants to manage your personal finances.
Details
- Author
- s-stefanov
- Categories
- Productivity, Finance
Jump to
Setup
Install Actual Budget in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/s-stefanov/actual-mcp
Follow the installation instructions in the repository README, then restart your MCP client.
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 fromActual Budgetusing natural language through LLMs. It exposes your accounts, transactions, and financial metrics through the Model Context Protocol (MCP).
- Account Listings- Browse all your accounts with their balances
- Account Details- View detailed information about specific accounts
- Transaction History- Access transaction data with complete details
- get-transactions- Retrieve and filter transactions by account, date, amount, category, or payee
- create-transaction- Create a new transaction in an account with optional category, payee, and notes
- update-transaction- Update an existing transaction with new category, payee, notes, or amount
- get-accounts- Retrieve a list of all accounts with their current balance and ID
- balance-history- View account balance changes over time
- spending-by-category- Generate spending breakdowns categorized by type
- monthly-summary- Get monthly income, expenses, and savings metrics
- get-grouped-categories- Retrieve a list of all category groups with their categories
- create-category- Create a new category within a category group
- update-category- Update an existing category's name or group
- delete-category- Delete a category
- create-category-group- Create a new category group
- update-category-group- Update a category group's name
- delete-category-group- Delete a category group
- get-payees- Retrieve a list of all payees with their details
- create-payee- Create a new payee
- update-payee- Update an existing payee's details
- delete-payee- Delete a payee
- get-rules- Retrieve a list of all transaction rules
- create-rule- Create a new transaction rule with conditions and actions
- update-rule- Update an existing transaction rule
- delete-rule- Delete a transaction rule
- financial-insights- Generate insights and recommendations based on your financial data
- budget-review- Analyze your budget compliance and suggest adjustments
- Node.js(v16 or higher)
- Actual Budgetinstalled and configured
- Claude Desktopor another MCP-compatible client
- Docker Desktop(optional)
git clone https://github.com/s-stefanov/actual-mcp.git cd actual-mcp
- Build the local docker image (optional):
docker build -t <local-image-name> .
- Configure environment variables (optional):
# 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 setACTUAL_BUDGET_ENCRYPTION_PASSWORDin addition toACTUAL_PASSWORD.
# If server auth and encryption/unlock use different passwords export ACTUAL_BUDGET_ENCRYPTION_PASSWORD="your-encryption-password"
To use this server with Claude Desktop, add it to your Claude configuration:
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
code %APPDATA%\Claude\claude_desktop_config.json
Add 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):
b. Using Docker (local or remote images):
{ "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:
- "What's my current account balance?"
- "Show me my spending by category last month"
- "How much did I spend on groceries in January?"
- "What's my savings rate over the past 3 months?"
- "Analyze my budget and suggest areas to improve"
[mcp_servers.actual-budget] url = "http://localhost:3000"
Point Codex at the same port you pass tonpm start -- --sse --port <PORT>.
To verify the server can connect to your Actual Budget data:
Since MCP servers communicate over stdio, debugging can be challenging. You can use theMCP Inspector:
npx @modelcontextprotocol/inspector node build/index.js``
-
index.ts- Main server implementation
- types.ts- Type definitions for API responses and parameters
- prompts.ts- Prompt templates for LLM interactions
- utils.ts- Helper functions for date formatting and more
This fork includes the following changes from the upstreams-stefanov/actual-mcp:
-
@actual-app/apibumped from^26.3.0to^26.5.0— updates the Actual Budget API client to the latest version for compatibility with newer Actual server releases.
- Balance cutoff fix—getAccountBalancecalls now pass a far-future cutoff date (2099-01-01`) so that future-dated pending transactions are included in balance calculations. Without this fix, banks that pre-date pending transactions (showing them in the future) would cause reported balances to be lower than the actual cleared balance.
Contributions are welcome! Please feel free to submit a Pull Request.
The only platform you need to get paid - all payments in one place, invoicing and accounting reconciliations with Adfin.
MCP server that gives AI agents and teams secure, role-based access to Stripe billing operations — customer lookups, subscription management, refunds, invoice history — without exposing Stripe dashboard credentials. Sub-100ms reads via local Stripe sync engine. 4 permission levels with audit logging. $14.99/month.
Easily query & find Belgian company finances
US/HK markets — 110 tools: real-time quotes, options, orders, fundamentals, alerts, DCA & portfolio
Interact with NAVI DeFi protocol on Sui blockchain for market data and transactions.
MCP server for managing accounting and taxes with Norman Finance.
Interact with Ramp's Developer API to run analysis on your spend and gain insights leveraging LLMs
WunderTrading MCP connects AI agents to live crypto trading execution on 20+ supported exchanges through a single MCP integration. Use it to turn AI-driven signals, market analysis, sentiment, screenshots, and custom strategy logic into real trades on exchanges including Binance, Bybit, Coinbase, Bitget, OKX, KuCoin, Hyperliquid, and BingX. Supports MCP and REST API workflows for order execution, trade management, and AI-powered automation.
Interact with the accounting data in your business using our official MCP server
AI-native trade business management for Australian tradies. 11 MCP tools for leads, quotes, jobs, invoicing, financials, and client CRM.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
