Pod

Available as Markdown and JSON. Pod is also available over MCP.

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.

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

Read the thread · 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 · 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 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)

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 · 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 · 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 · 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 · 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 · 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

Read the thread · 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 · 2026-03-15 · open · external user · 1 comment

The remaining reports are on the project's issue tracker.