Actual Budget MCP Server
MCP server for integrating Actual Budget with Claude and other LLM assistants.
Overview
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).
Features
Resources
- 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
Tools
get-transactions
- Retrieve and filter transactions by account, date, amount, category, or payeespending-by-category
- Generate spending breakdowns categorized by typemonthly-summary
- Get monthly income, expenses, and savings metricsbalance-history
- View account balance changes over time
Prompts
financial-insights
- Generate insights and recommendations based on your financial databudget-review
- Analyze your budget compliance and suggest adjustments
Installation
Prerequisites
- Node.js (v16 or higher)
- Actual Budget installed and configured
- Claude Desktop or another MCP-compatible client
Setup
Clone the repository:
git clone https://github.com/s-stefanov/mcp-actualbudget.git cd mcp-actualbudget
Install dependencies:
npm install
Build the server:
npm run build
Configure environment variables (optional): ```bash
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"
## 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:
code %APPDATA%\Claude\claude_desktop_config.json
Add the following to your configuration:
{
"mcpServers": {
"actualBudget": {
"command": "node",
"args": ["/absolute/path/to/actual-budget-mcp/build/index.js"],
"env": {
"ACTUAL_DATA_DIR": "/path/to/your/actual/data"
}
}
}
}
After saving the configuration, restart Claude Desktop.
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"
Development
For development with auto-rebuild:
npm run watch
Testing the connection to Actual
To verify the server can connect to your Actual Budget data:
node build/index.js --test-resources
Debugging
Since MCP servers communicate over stdio, debugging can be challenging. You can use the MCP Inspector:
npx @modelcontextprotocol/inspector node build/index.js
Project Structure
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 more
License
MIT
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Releases
Releases are automated using Changesets and GitHub Actions. On every push to main
, a release PR is created and, once merged, a new version is published to npm and a Docker image is built and pushed to GitHub Container Registry.
- To create a release, add a changeset with
npx changeset
and merge to main. - The release workflow will handle npm publishing and Docker image publishing automatically.