actual

This MCP server exposes your Actual Budget data to Claude and other MCP clients via the Model Context Protocol. It provides access to accounts, balances, and a range of transactional data, and it offers tools for managing your budget programmatically. You can retrieve account listings, view account details, fetch transaction histories, and run analytical queries such as spending by category and monthly summaries. The server also supports creation and modification of categories, payees, and rules, enabling incremental budgeting workflows through natural language prompts. Prompts like financial-insights and budget-review help you derive actionable recommendations from your data. To use it with Claude Desktop or another MCP client, point the client at the running MCP endpoint and enable write access if your workflow requires modifying data.

Prerequisites:

• Node.js 16 or higher
• Actual Budget installed and configured
• Claude Desktop or another MCP-compatible client (optional for testing)
• Docker Desktop (optional for containerized usage)

Local setup (recommended for development and testing):

1. Clone the repository and install dependencies

git clone https://github.com/s-stefanov/actual-mcp.git
cd actual-mcp
npm install

2. Build the server (production bundle if applicable)

npm run build

3. Run the MCP server locally using npx (example configuration)

npx -y actual-mcp --enable-write

4. Optional: Build and run via Docker

docker build -t your-local/actual-mcp .
docker run -i --rm -p 3000:3000 -e ACTUAL_PASSWORD=your-password -e ACTUAL_SERVER_URL=https://your-actual-server.com -e ACTUAL_BUDGET_SYNC_ID=your-budget-id your-local/actual-mcp --enable-write

5. Configure environment variables (recommended):

export ACTUAL_DATA_DIR="/path/to/your/data"           # optional if using server URL
export ACTUAL_PASSWORD="your-password"
export ACTUAL_SERVER_URL="http://your-actual-server.com"
export ACTUAL_BUDGET_SYNC_ID="your-budget-id"

Tip: If you want to expose the server remotely, consider using SSE mode and Bearer authentication as described in the README examples.

Notes and tips:

• Use --enable-write to enable tools that can modify your Actual Budget data (create/update operations).
• When exposing the MCP server publicly, consider enabling Bearer authentication and setting BEARER_TOKEN to restrict access.
• ACTUAL_DATA_DIR is optional if you rely on a remote Actual Budget server via ACTUAL_SERVER_URL.
• For Claude Desktop integration, you can configure either npx-based usage or a local node execution path as shown in the README examples.
• If you run via Docker, ensure port mappings and volume mounts align with your data directory and environment variables.
• The server supports a broad set of tools (transactions, accounts, categories, payees, rules) and reporting prompts (financial-insights, budget-review) to drive natural-language querying.
• For development and debugging, use the MCP Inspector to observe stdio-based communication or run node build/index.js with the appropriate flags.