actual-mcp

# 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](https://actualbudget.com/) 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 #### Transaction & Account Management - **`get-transactions`** - Retrieve and filter transactions by account, date, amount, category, or payee - **`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 ### Prompts - **`financial-insights`** - Generate insights and recommendations based on your financial data - **`budget-review`** - Analyze your budget compliance and suggest adjustments ## Installation ### Prerequisites - [Node.js](https://nodejs.org/) (v16 or higher) - [Actual Budget](https://actualbudget.com/) installed and configured - [Claude Desktop](https://claude.ai/download) or another MCP-compatible client - [Docker Desktop](https://www.docker.com/products/docker-desktop) (optional) ### Remote access Pull the latest docker image: ``` docker pull sstefanov/actual-mcp:latest ``` ### Local setup 1. Clone the repository: ```bash git clone https://github.com/sstefanov/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 <local-image-name> . ``` 5. 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: ```bash code %APPDATA%\Claude\claude_desktop_config.json ``` Add the following to your configuration... ### a. Using Node.js (npx version): ```json { "mcpServers": { "actualBudget": { "command": "node", "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" } } } } ``` ### b. Using Docker (local or remote images): ```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. > 💡 `ACTUAL_DATA_DIR` 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" ## Development For development with auto-rebuild: ```bash npm run watch ``` ### Testing the connection to Actual To verify the server can connect to your Actual Budget data: ```bash node build/index.js --test-resources ``` ### Debugging Since MCP servers communicate over stdio, debugging can be challenging. You can use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector): ```bash npx @modelcontextprotocol/inspector node build/index.js ``` ## Project Structure - `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 ## License MIT ## Contributing Contributions are welcome! Please feel free to submit a Pull Request.