Skip to content
Back to search

actual-mcp

Model Context Protocol for Actual Budget API

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/s-stefanov/actual-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/s-stefanov/actual-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/s-stefanov--actual-mcp/badge.svg)](/listings/s-stefanov--actual-mcp)

HTML

<a href="/listings/s-stefanov--actual-mcp"><img src="/api/listings/s-stefanov--actual-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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:

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

2. Install dependencies:

npm install

3. Build the server:

npm run build

4. Build the local docker image (optional):

docker build -t <local-image-name> .

5. 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 set `ACTUAL_BUDGET_ENCRYPTION_PASSWORD` in addition to `ACTUAL_PASSWORD`.

# If server auth and encryption/unlock use different passwords
export ACTUAL_BUDGET_ENCRYPTION_PASSWORD="your-encryption-password"

Connection lifecycle

The server keeps one shared Actual connection for its entire lifetime and serializes budget operations through it. Downloaded data is re-synced when it exceeds the `ACTUAL_SYNC_TTL_MS` freshness window. In both stdio and HTTP modes, SIGINT and SIGTERM drain in-flight work before the server shuts down. Actual is no longer initialized and shut down for each tool call.

Report semantics

- Balances and balance histories are capped as of today; future-dated transactions are excluded, and the current-month balance-history row is partial. - Closed on-budget accounts remain included in historical reports; closed off-budget accounts stay excluded by default. - Monthly income follows Actual's income-group metadata. Refunds net against expenses, zero-activity months count in averages, and uncategorized transfer pairs are skipped. - The former Investments bucket is removed from monthly summaries.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 376 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Actual Budget MCP Server
  2. MCP server for integrating Actual Budget with Claude and other LLM assistants.
  3. ## Overview
  4. 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).
  5. ## Features
  6. ### Resources
  7. - **Account Listings** - Browse all your accounts with their balances
  8. - **Account Details** - View detailed information about specific accounts
  9. - **Transaction History** - Access transaction data with complete details
  10. ### Tools
  11. #### Transaction & Account Management
  12. - **`get-transactions`** - Retrieve and filter transactions by account, date, amount, category, or payee
  13. - **`create-transaction`** - Create a new transaction in an account with optional category, payee, and notes
  14. - **`update-transaction`** - Update an existing transaction with new category, payee, notes, or amount
  15. - **`get-accounts`** - Retrieve a list of all accounts with their current balance and ID
  16. - **`balance-history`** - View account balance changes over time
  17. #### Reporting & Analytics
  18. - **`spending-by-category`** - Generate spending breakdowns categorized by type
  19. - **`monthly-summary`** - Get monthly income, expenses, and savings metrics
  20. - **`budget-vs-actual`** - Compare budgeted amounts against actual spending per category
  21. - **`net-worth`** - Track assets, liabilities, and net worth across all accounts over time
  22. - **`category-trends`** - See how spending in each category moves month over month, with trend direction
  23. - **`spending-by-payee`** - Rank payees by how much was spent with (or received from) each one
  24. - **`cash-flow`** - Report income, expenses, and net cash flow per month or week
  25. > The five tools above return JSON rather than markdown, so amounts stay machine-readable. Every amount is an integer number of cents, and each response carries an `amountsIn` field describing the sign conventions it uses.
  26. #### Custom Reports & Dashboards
  27. - **`get-custom-reports`** - Retrieve every saved custom report from the Reports section
  28. - **`create-custom-report`** - Create a saved custom report
  29. - **`update-custom-report`** - Update fields on a saved custom report, leaving the rest unchanged
  30. - **`delete-custom-report`** - Delete a saved custom report
  31. - **`get-dashboards`** - Retrieve every dashboard page and the widgets laid out on it
  32. - **`add-dashboard-widget`** - Add a widget to a dashboard page
  33. - **`update-dashboard-widget`** - Update a widget's configuration, position, or size
  34. - **`remove-dashboard-widget`** - Remove a widget from its page
  35. - **`organize-dashboard`** - Reposition and resize several widgets at once
  36. - **`create-dashboard-page`** / **`rename-dashboard-page`** / **`delete-dashboard-page`** - Manage dashboard pages
  37. #### Categories
  38. - **`get-grouped-categories`** - Retrieve a list of all category groups with their categories
  39. - **`create-category`** - Create a new category within a category group
  40. - **`update-category`** - Update an existing category's name or group
  41. - **`delete-category`** - Delete a category
  42. - **`create-category-group`** - Create a new category group
  43. - **`update-category-group`** - Update a category group's name
  44. - **`delete-category-group`** - Delete a category group
  45. #### Payees
  46. - **`get-payees`** - Retrieve a list of all payees with their details
  47. - **`create-payee`** - Create a new payee
  48. - **`update-payee`** - Update an existing payee's details
  49. - **`delete-payee`** - Delete a payee
  50. - **`merge-payees`** - Merge duplicate payees into a single target payee
  51. #### Rules
  52. - **`get-rules`** - Retrieve a list of all transaction rules
  53. - **`create-rule`** - Create a new transaction rule with conditions and actions
  54. - **`update-rule`** - Update an existing transaction rule
  55. - **`delete-rule`** - Delete a transaction rule
  56. ### Prompts
  57. - **`financial-insights`** - Generate insights and recommendations based on your financial data
  58. - **`budget-review`** - Analyze your budget compliance and suggest adjustments
  59. ## Installation
  60. ### Prerequisites
  61. - [Node.js](https://nodejs.org/) (v16 or higher)
  62. - [Actual Budget](https://actualbudget.com/) installed and configured
  63. - [Claude Desktop](https://claude.ai/download) or another MCP-compatible client
  64. - [Docker Desktop](https://www.docker.com/products/docker-desktop) (optional)
  65. ### Remote access
  66. Pull the latest docker image:
  67. ```
  68. docker pull sstefanov/actual-mcp:latest
  69. ```
  70. ### Local setup
  71. 1. Clone the repository:
  72. ```bash
  73. git clone https://github.com/s-stefanov/actual-mcp.git
  74. cd actual-mcp
  75. ```
  76. 2. Install dependencies:
  77. ```bash
  78. npm install
  79. ```
  80. 3. Build the server:
  81. ```bash
  82. npm run build
  83. ```
  84. 4. Build the local docker image (optional):
  85. ```bash
  86. docker build -t <local-image-name> .
  87. ```
  88. 5. Configure environment variables (optional):
  89. ```bash
  90. # Path to your Actual Budget data directory (default: ~/.actual)
  91. export ACTUAL_DATA_DIR="/path/to/your/actual/data"
  92. # If using a remote Actual server
  93. export ACTUAL_SERVER_URL="https://your-actual-server.com"
  94. export ACTUAL_PASSWORD="your-password"
  95. # Specific budget to use (optional)
  96. export ACTUAL_BUDGET_SYNC_ID="your-budget-id"
  97. # How long downloaded data stays fresh before the server re-syncs, in ms
  98. # (default: 60000). Use 0 to sync before every call, or -1 to never sync.
  99. export ACTUAL_SYNC_TTL_MS="60000"
  100. ```
  101. Optional: separate encryption budget password
  102. If your Actual setup requires a different password to unlock the local/encrypted budget data than the server authentication password, you can set `ACTUAL_BUDGET_ENCRYPTION_PASSWORD` in addition to `ACTUAL_PASSWORD`.
  103. ```bash
  104. # If server auth and encryption/unlock use different passwords
  105. export ACTUAL_BUDGET_ENCRYPTION_PASSWORD="your-encryption-password"
  106. ```
  107. Optional: OpenID servers (session token auth)
  108. If your Actual server uses OpenID login (for example Google) with `ACTUAL_OPENID_ENFORCE=true`, password login is disabled, so `ACTUAL_PASSWORD` can't be used. Instead, sign in to Actual in a browser and pass the resulting session token. It takes precedence over `ACTUAL_PASSWORD`.
  109. ```bash
  110. export ACTUAL_SERVER_URL="https://your-actual-server.com"
  111. export ACTUAL_SESSION_TOKEN="your-session-token"
  112. ```
  113. To find the token, sign in to Actual in your browser, open DevTools, and go to **Application → IndexedDB → actual → asyncStorage**. The value of the `user-token` key is your session token. It's a UUID (e.g. `3f2b8c1e-9a4d-4e7b-8c2a-1d5e6f7a8b9c`), not a long JWT-style bearer token. You can check it with `curl -H "X-ACTUAL-TOKEN: <token>" https://your-actual-server.com/account/validate`, which should return `"validated": true`. Treat it like a password: it grants full access to your budgets. How long it stays valid depends on the server's `ACTUAL_TOKEN_EXPIRATION` setting. If it is invalid or expired, the MCP server still starts, but tool calls fail with `Authentication failed: invalid or expired session token`, because the server connects to Actual on the first request (`--test-resources` reports the error immediately). Sign in again, replace the token, and restart the MCP server.
  114. ### Connection lifecycle
  115. The server keeps one shared Actual connection for its entire lifetime and serializes budget operations through it. Downloaded data is re-synced when it exceeds the `ACTUAL_SYNC_TTL_MS` freshness window. In both stdio and HTTP modes, SIGINT and SIGTERM drain in-flight work before the server shuts down. Actual is no longer initialized and shut down for each tool call.
  116. ### Report semantics
  117. - Balances and balance histories are capped as of today; future-dated transactions are excluded, and the current-month balance-history row is partial.
  118. - Closed on-budget accounts remain included in historical reports; closed off-budget accounts stay excluded by default.
  119. - Monthly income follows Actual's income-group metadata. Refunds net against expenses, zero-activity months count in averages, and uncategorized transfer pairs are skipped.
  120. - The former Investments bucket is removed from monthly summaries.
  121. ## Usage with Claude Desktop
  122. To use this server with Claude Desktop, add it to your Claude configuration:
  123. On MacOS:
  124. ```bash
  125. code ~/Library/Application\ Support/Claude/claude_desktop_config.json
  126. ```
  127. On Windows:
  128. ```bash
  129. code %APPDATA%\Claude\claude_desktop_config.json
  130. ```
  131. Add the following to your configuration...
  132. ### a. Using Node.js (npx version):
  133. ```json
  134. {
  135. "mcpServers": {
  136. "actualBudget": {
  137. "command": "npx",
  138. "args": ["-y", "actual-mcp", "--enable-write"],
  139. "env": {
  140. "ACTUAL_DATA_DIR": "path/to/your/data",
  141. "ACTUAL_PASSWORD": "your-password",
  142. "ACTUAL_SERVER_URL": "http://your-actual-server.com",
  143. "ACTUAL_BUDGET_SYNC_ID": "your-budget-id"
  144. }
  145. }
  146. }
  147. }
  148. ### a. Using Node.js (local only):
  149. ```json
  150. {
  151. "mcpServers": {
  152. "actualBudget": {
  153. "command": "node",
  154. "args": ["/path/to/your/clone/build/index.js", "--enable-write"],
  155. "env": {
  156. "ACTUAL_DATA_DIR": "path/to/your/data",
  157. "ACTUAL_PASSWORD": "your-password",
  158. "ACTUAL_SERVER_URL": "http://your-actual-server.com",
  159. "ACTUAL_BUDGET_SYNC_ID": "your-budget-id"
  160. }
  161. }
  162. }
  163. }
  164. ```
  165. ### b. Using Docker (local or remote images):
  166. ```json
  167. {
  168. "mcpServers": {
  169. "actualBudget": {
  170. "command": "docker",
  171. "args": [
  172. "run",
  173. "-i",
  174. "--rm",
  175. "-v",
  176. "/path/to/your/data:/data",
  177. "-e",
  178. "ACTUAL_PASSWORD=your-password",
  179. "-e",
  180. "ACTUAL_SERVER_URL=https://your-actual-server.com",
  181. "-e",
  182. "ACTUAL_BUDGET_SYNC_ID=your-budget-id",
  183. "sstefanov/actual-mcp:latest",
  184. "--enable-write"
  185. ]
  186. }
  187. }
  188. }
  189. ```
  190. After saving the configuration, restart Claude Desktop.
  191. > 💡 `ACTUAL_DATA_DIR` is optional if you're using `ACTUAL_SERVER_URL`.
  192. > 💡 Use `--enable-write` to enable write-access tools.
  193. ## Running an SSE Server
  194. To expose the server over a port using Docker:
  195. ```bash
  196. docker run -i --rm \
  197. -p 3000:3000 \
  198. -v "/path/to/your/data:/data" \
  199. -e ACTUAL_PASSWORD="your-password" \
  200. -e ACTUAL_SERVER_URL="http://your-actual-server.com" \
  201. -e ACTUAL_BUDGET_SYNC_ID="your-budget-id" \
  202. -e BEARER_TOKEN="your-bearer-token" \
  203. sstefanov/actual-mcp:latest \
  204. --sse --enable-write --enable-bearer
  205. ```
  206. > ⚠️ Important: When using --enable-bearer, the BEARER_TOKEN environment variable must be set.
  207. > 🔒 This is highly recommended if you're exposing your server via a public URL.
  208. ## Example Queries
  209. Once connected, you can ask Claude questions like:
  210. - "What's my current account balance?"
  211. - "Show me my spending by category last month"
  212. - "How much did I spend on groceries in January?"
  213. - "What's my savings rate over the past 3 months?"
  214. - "Which categories am I overspending on this month?"
  215. - "How has my net worth changed over the past year?"
  216. - "Which payees do I spend the most with?"
  217. - "Is my grocery spending trending up or down?"
  218. - "Analyze my budget and suggest areas to improve"
  219. - "What custom reports do I have?"
  220. - "Add a net worth widget to my Spending Plan dashboard"
  221. - "Rearrange my dashboard so the cash flow card is full width at the top"
  222. ## Usage with Codex CLI
  223. Example Codex configuration:
  224. In `~/.codex/config.toml`:
  225. ```toml
  226. [mcp_servers.actual-budget]
  227. url = "http://localhost:3000"
  228. ```
  229. Point Codex at the same port you pass to `npm start -- --sse --port <PORT>`.
  230. ## Development
  231. For development with auto-rebuild:
  232. ```bash
  233. npm run watch
  234. ```
  235. ### Testing the connection to Actual
  236. To verify the server can connect to your Actual Budget data:
  237. ```bash
  238. node build/index.js --test-resources
  239. ```
  240. ### Debugging
  241. Since MCP servers communicate over stdio, debugging can be challenging. You can use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
  242. ```bash
  243. npx @modelcontextprotocol/inspector node build/index.js
  244. ```
  245. ### E2E validation gate
  246. The end-to-end test suite (`vitest.e2e.config.ts`) spins up a real Actual Budget server in a Docker container (via Testcontainers), seeds a budget, and drives it through a real MCP client over stdio to verify accounts, transactions, categories, payees, rules, and imports actually persist. It requires Docker to be running locally.
  247. In CI, the `e2e-test` job in `.github/workflows/pr-validation.yml` only runs on release-please PRs (branch prefix `release-please--`) or when a PR is given the `run-e2e` label — it does not run on every PR by default, since it needs Docker and takes longer than the standard checks.
  248. To run it locally:
  249. ```bash
  250. npm run build && npm run test:e2e
  251. ```
  252. Docker must be installed and running; the test suite pulls and starts the Actual server image automatically.
  253. ## Project Structure
  254. - `index.ts` - Main server implementation
  255. - `types.ts` - Type definitions for API responses and parameters
  256. - `prompts.ts` - Prompt templates for LLM interactions
  257. - `utils.ts` - Helper functions for date formatting and more
  258. ## Registry & Discovery
  259. `actual-mcp` is published to the [official MCP Registry](https://registry.modelcontextprotocol.io)
  260. as `io.github.s-stefanov/actual-mcp`. Registry metadata lives in
  261. [`server.json`](./server.json) and is published automatically on each release
  262. (see `.github/workflows/release-please.yml`).
  263. It advertises two transports on the npm package — `stdio` (default) and
  264. `streamable-http` (via the `--sse` flag). (A Docker image is also published,
  265. but is not yet listed as a registry package.)
  266. Post-release directory listings are tracked in
  267. [`docs/mcp-registry-checklist.md`](./docs/mcp-registry-checklist.md).
  268. ## License
  269. MIT
  270. ## Contributing
  271. Contributions are welcome! Please feel free to submit a Pull Request.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.