# Reported issues for Actual Budget MCP Server Pod holds 19 of 32 GitHub reports that passed its relevance review. This can include external user reports, maintainer-confirmed bugs, and concrete feature gaps. Treat them as evidence to inspect, not a count of distinct defects. Back to [Actual Budget MCP Server](/mcp/actual-budget-mcp-server). ## Most discussed ### Issues connecting `actual-mcp` to Actual Budget server (`ERR_INVALID_URL` / `out-of-sync-migrations`) ## Thanks 🙏 First of all, thank you for this project and all the work put into it! --- ## Vision I want to let my **Finance Agent (LibreChat)** access and manage my financial information in **Actual Budget** through **Actual MCP**. --- ## Context / Background * **Environment:** Synology NAS, Docker-based setup. * Running three separate Docker networks/containers: * **LibreChat** – running, fully operational. * **Actual Budget** – running in a separate network, accessible and… [Read the thread](https://github.com/s-stefanov/actual-mcp/issues/25) · 2025-09-22 · open · external user · 6 comments ### update-transaction crashes MCP server when using payee_name parameter ## Bug Calling `update-transaction` with the `payee_name` parameter crashes the MCP server process. The server disconnects and must be reconnected. This happens consistently — every call with `payee_name` triggers the crash. ## Steps to reproduce 1. Call `update-transaction` with a valid transaction ID and a `payee_name` string (e.g., `"payee_name": "Some Payee"`) 2. The MCP server process crashes with a connection closed error 3. All subsequent tool calls fail until the server is… [Read the thread](https://github.com/s-stefanov/actual-mcp/issues/150) · 2026-04-03 · closed · external user · 3 comments ### Did you stop publishing docker image for linux/arm64? I don't see it since tag [v1.2.0](https://hub.docker.com/layers/sstefanov/actual-mcp/v1.2.0/images/sha256-5872804240ec81c97adb9c21ef40ba90b27a3bae7c641468707d4c6d68917123) on the Docker hub https://hub.docker.com/r/sstefanov/actual-mcp/tags ``` docker run ``` fails with error on Raspberry P 4 ``` WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested exec /usr/local/bin/node: exec format error… [Read the thread](https://github.com/s-stefanov/actual-mcp/issues/104) · 2026-02-22 · closed · external user · 2 comments ### Image on Docker Hub is incompatible with non ARM hosts Trying to run it with the following compose file, but faced with this error: ```console actual_mcp The requested image's platform (linux/arm64/v8) does not match the detected host platform (linux/amd64/v3) and no specific platform was requested ``` It seems only arm images are published on Docker hub (i'm on x64/amd) ```yaml services: actual_server: image: docker.io/actualbudget/actual-server container_name: actual_server env_file: actualbudget.env ports: - 5006:5006… [Read the thread](https://github.com/s-stefanov/actual-mcp/issues/21) · 2025-09-09 · closed · external user · 2 comments ### Compatibility issue with Actual Budget v26.7.0: out-of-sync-migrations ## Description When running actual-mcp against an Actual Budget server running v26.7.0, loading the budget fails with an `out-of-sync-migrations` error. ## Environment - actual-mcp: Docker image `sstefanov/actual-mcp:latest` - Actual Budget server: v26.7.0 - Transport: SSE - Configuration includes `ACTUAL_SERVER_URL` and `ACTUAL_BUDGET_SYNC_ID` ## Error log ```text [Breadcrumb] { message: 'Closing budget' } Error updating Error: out-of-sync-migrations at checkDatabaseValidity… [Read the thread](https://github.com/s-stefanov/actual-mcp/issues/189) · 2026-07-16 · closed · external user · 1 comment ### ACTUAL_DATA_DIR on different host My Actual installation is located on a different host, and thus the data directory is not directly accessible. Does this mean I am unable to use the mcp server? [Read the thread](https://github.com/s-stefanov/actual-mcp/issues/188) · 2026-07-15 · closed · external user · 1 comment ### RangeError: Maximum call stack size exceeded — streamableTransport.onclose recurses via sessionServer.close() (Streamable HTTP) ## Summary When a Streamable HTTP session closes, the `streamableTransport.onclose` handler at [src/index.ts#L237-L243](https://github.com/s-stefanov/actual-mcp/blob/v1.11.2/src/index.ts#L237) calls `sessionServer.close()`, which transitively calls `transport.close()`, which re-fires `streamableTransport.onclose`. Infinite recursion crashes the Node process with `RangeError: Maximum call stack size exceeded`. With `--restart` policies the container auto-recovers, but every client disconnect… [Read the thread](https://github.com/s-stefanov/actual-mcp/issues/170) · 2026-05-20 · closed · outside contributor · 1 comment ### out-of-sync-migrations against actual-server 26.5.0 (bundled api@26.3.0 too old) ## Repro 1. Run actual-server 26.5.0 (current `latest`). 2. Launch `sstefanov/actual-mcp:latest` (v1.11.2 on Docker Hub) with valid `ACTUAL_SERVER_URL` / `ACTUAL_PASSWORD` / `ACTUAL_BUDGET_SYNC_ID` (groupId form). 3. Call `get-accounts` (or any tool requiring budget download). ## Result ``` Error updating Error: out-of-sync-migrations at checkDatabaseValidity (.../@actual-app/api/dist/app/bundle.api.js:124664) at migrate (...:124672) at runMigrations (...:124680) at… [Read the thread](https://github.com/s-stefanov/actual-mcp/issues/165) · 2026-05-08 · closed · external user · 1 comment ## Most recent ### create-rule rejects stage: null (the documented default-stage value) with 'Invalid rule stage: null' ## Summary Calling `create-rule` with `stage: null` — the tool's own documented way to create a default-stage rule — fails with `Invalid rule stage: null`, even though both the tool's schema and Actual's underlying rule validator explicitly allow `null`. ## Expected behavior A rule created with `stage: null` should succeed and be stored with the default stage, exactly like the `stage` Actual reports (as literal JSON `null`) for every pre-existing default-stage rule via `get-rules`. This is… [Read the thread](https://github.com/s-stefanov/actual-mcp/issues/213) · 2026-09-03 · open · external user · 0 comments ### get-transactions requires accountId, unlike every other filtering tool in this server ## Summary `get-transactions` requires `accountId` (`z.string()`, not optional), so there's no way to search transactions by payee/category across all accounts — every other filtering tool in this codebase supports that. ## Expected behavior Given a `payeeName`/`categoryName`/date-range filter, it should be possible to find matching transactions across all accounts without already knowing which account holds them — matching the pattern already established by `spending-by-category` and… [Read the thread](https://github.com/s-stefanov/actual-mcp/issues/212) · 2026-09-03 · open · external user · 0 comments ### `get-transactions` reports split-transaction parents as "(Uncategorized)" and omits subtransactions ## Summary When a transaction is a split (has child subtransactions), the `get-transactions` tool reports the parent row as `(Uncategorized)`. The child transactions and their categories are never shown, so the transaction appears uncategorized even though it is fully categorized across its subtransactions. ## Expected behavior Split transactions should not be reported as uncategorized. The tool should surface the subtransactions (each with its own category), for example by expanding the… [Read the thread](https://github.com/s-stefanov/actual-mcp/issues/208) · 2026-08-14 · open · external user · 0 comments ### Null `SYNC_SERVER` error when using data directory When running `v1.12.0` with actual `v2026.7.0` it fails when use `ACTUAL_DATA_DIR`. This error does not occur when using `ACTUAL_SERVER_URL`. ``` [Exception] TypeError: Cannot read properties of null (reading 'SYNC_SERVER') at _fullSync (/app/node_modules/@actual-app/api/dist/index.js:63472:48) at async /app/node_modules/@actual-app/api/dist/index.js:63402:14 at async initialFullSync (/app/node_modules/@actual-app/api/dist/index.js:63391:17) at async Object.syncBudget [as… [Read the thread](https://github.com/s-stefanov/actual-mcp/issues/192) · 2026-07-30 · open · external user · 0 comments ### Compatibility issues with Actual Budget Server v26.6.0+ due to outdated @actual-app/api ### Description With the release of Actual Budget Server v26.6.0+, databases are migrated to schemas that are incompatible with the older `@actual-app/api` version (`^26.5.0`) used in this repository. This causes the MCP server to crash on startup with an `out-of-sync-migrations` error when trying to load the budget. ### Proposed Fix Bump `@actual-app/api` and `@actual-app/core` to `^26.6.0` to ensure full compatibility with the latest migrations. --- *This issue was identified and documented… [Read the thread](https://github.com/s-stefanov/actual-mcp/issues/181) · 2026-06-16 · closed · external user · 0 comments ### get-transactions drops transfer_id, making transfer detection impossible client-side ## Problem `get-transactions` returns a markdown table with columns `ID | Date | Payee | Category | Amount | Cleared | Notes`. The underlying Actual API (`@actual-app/api`) returns `transfer_id` on every transaction (set to the linked counterpart's id iff the row is part of a transfer), and `src/core/types/domain.ts` already declares `transfer_id?: string` on the `Transaction` interface — but `src/tools/get-transactions/transaction-mapper.ts` discards it before the response is built. As a… [Read the thread](https://github.com/s-stefanov/actual-mcp/issues/168) · 2026-05-17 · closed · outside contributor · 0 comments ### Error when initially testing server connection: Authentication failed: too-many-requests I followed the steps in the `README.md` to build the server and test it using `node build/index.js --test-resources`, but the output of that test shows: ```bash ➜ actual-mcp git:(main) node build/index.js --test-resources Testing resources... Initializing Actual Budget API... Failed to initialize Actual Budget API: Error: Authentication failed: too-many-requests at Object.init… [Read the thread](https://github.com/s-stefanov/actual-mcp/issues/164) · 2026-05-08 · open · external user · 0 comments ### [Feature request] Account CRUD tools ### Background `@actual-app/api` exposes the full account-management surface (`createAccount`, `updateAccount`, `closeAccount`, `reopenAccount`, `deleteAccount`), but none of these are available through `actual-mcp`. Agentic workflows that need to set up or tidy accounts currently have to fall back to the web UI, which breaks multi-step automation flows. Three of these tools were proposed previously in #102 (bundled with a v26 deps upgrade, since landed via #127). That PR was closed by… [Read the thread](https://github.com/s-stefanov/actual-mcp/issues/162) · 2026-04-21 · open · external user · 0 comments ### stdio: @actual-app/api debug logs on stdout break JSON-RPC parsing ## Description When running actual-mcp in stdio mode (e.g. from Claude Desktop), the `@actual-app/api` library writes debug and breadcrumb log lines directly to **stdout** during initialization and sync. Since the MCP stdio transport expects only valid JSON-RPC messages on stdout, the client fails to parse these lines. On Claude Desktop (Windows), this results in visible error banners on every startup. ## Errors ``` Unexpected token 'B', "[Breadcrumb] {" is not valid JSON Unexpected token… [Read the thread](https://github.com/s-stefanov/actual-mcp/issues/161) · 2026-04-20 · open · external user · 0 comments ### Streamable HTTP sessions block new connections (concurrency issue) ## Description When a Streamable HTTP session exists (from a prior client connection or diagnostic `curl` request), subsequent `initialize` requests to `/mcp` fail silently with a 500 Internal Server Error. This prevents new clients (e.g., Claude.ai Custom Connector) from connecting until the server is restarted. ## Environment - **actual-mcp** v1.11.1 - **@modelcontextprotocol/sdk** v1.27.1 - Deployed via Podman (rootless) on Raspberry Pi 3 with Cloudflare Tunnel - Client: Claude.ai Custom… [Read the thread](https://github.com/s-stefanov/actual-mcp/issues/152) · 2026-04-06 · open · outside contributor · 0 comments ### SSE transport crashes on second connection — single Server instance reused across all connections # SSE transport crashes on second connection: "Already connected to a transport" ## Description When running `actual-mcp` in SSE mode (`--sse`), the server crashes immediately when a second client opens an SSE connection. The MCP SDK's `Server` class requires a separate instance per connection, but the current SSE handler in `build/index.js` reuses a single `Server` instance across all connections. This makes the SSE transport unusable with any MCP gateway or proxy that maintains multiple… [Read the thread](https://github.com/s-stefanov/actual-mcp/issues/143) · 2026-03-15 · open · external user · 1 comment The remaining reports are on [the project's issue tracker](https://github.com/s-stefanov/actual-mcp/issues).