Actual Budget MCP server exposing API functionality
npm install actual-mcpMCP 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).
- 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
#### Transaction & Account Management
- 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
#### Reporting & Analytics
- spending-by-category - Generate spending breakdowns categorized by type
- monthly-summary - Get monthly income, expenses, and savings metrics
#### Categories
- 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
#### Payees
- 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
#### Rules
- 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 Budget installed and configured
- Claude Desktop or another MCP-compatible client
- Docker Desktop (optional)
Pull the latest docker image:
``
docker pull sstefanov/actual-mcp:latest
1. Clone the repository:
`bash`
git clone https://github.com/s-stefanov/actual-mcp.git
cd actual-mcp
2. Install dependencies:
`bash`
npm install
3. Build the server:
`bash`
npm run build
4. Build the local docker image (optional):
`bash`
docker build -t
5. Configure environment variables (optional):
`bashPath to your Actual Budget data directory (default: ~/.actual)
export ACTUAL_DATA_DIR="/path/to/your/actual/data"
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
in addition to ACTUAL_PASSWORD.`bash
If server auth and encryption/unlock use different passwords
export ACTUAL_BUDGET_ENCRYPTION_PASSWORD="your-encryption-password"
`Usage with Claude Desktop
To use this server with Claude Desktop, add it to your Claude configuration:
On MacOS:
bash
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
`On Windows:
bash
code %APPDATA%\Claude\claude_desktop_config.json
`Add the following to your configuration...
$3
json
{
"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"
}
}
}
}$3
`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"
}
}
}
}
`$3
json
{
"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.
> 💡
is optional if you're using ACTUAL_SERVER_URL.> 💡 Use
--enable-write to enable write-access tools.Running an SSE Server
To expose the server over a port using Docker:
`bash
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.
Example Queries
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"
Usage with Codex CLI
Example Codex configuration:
In
:
`toml
[mcp_servers.actual-budget]
url = "http://localhost:3000"
`Point Codex at the same port you pass to
.Development
For development with auto-rebuild:
`bash
npm run watch
`$3
To verify the server can connect to your Actual Budget data:
bash
node build/index.js --test-resources
`$3
Since MCP servers communicate over stdio, debugging can be challenging. You can use the MCP Inspector:
bash
npx @modelcontextprotocol/inspector node build/index.js
`Project Structure
-
- 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 moreMIT
Contributions are welcome! Please feel free to submit a Pull Request.