Actual Budget

actual-budget-mcp

予算について話しましょう。Actual Budget を Claude に接続する MCP サーバーです。お金の使い道を尋ねれば、実際の分析結果が返ってきます。安心して変更を任せることもできます。

Actual Budget 公式コミュニティプロジェクト一覧に掲載されています。

主な機能

• 検索だけではない、本格的な分析 - 予測、カテゴリの傾向、予算と実績の比較、月ごとの概要
• 安心して任せられる変更 - 削除のたびに削除内容を事前表示して確認を待ちます。ACTUAL_READ_ONLY=1 を設定すると、書き込みツールをモデルから完全に隠せます（安全性）
• 実情に合わせた複数通貨対応 - 通貨記号の表示だけでなく、金額の分割や残差の調整にも対応
• 同期のずれから復旧 - @actual-app/api とサーバー間で不一致が起きた場合、repair_sync でローカルの同期状態を再構築できます。これを行わないと、すべてのツールでエラーが発生し続けます
• 自然な言葉で予算について質問 - 「今月、食費にいくら使った？」や「予算超過している項目はある？」
• 取引の作成と管理 - アプリを開かずに、支出や振替を追加・編集できます
• カテゴリ、受取先、ルールの管理 - アプリを開かずに、作成・読み取り・更新・削除（CRUD）をすべて行えます
• ID ではなく名前を使用 - a1b2c3d4-... の代わりに「Wallet」と指定できます。あいまいな場合は候補を提示します
• 英語とスペイン語の自然な日付表現に対応 - 「先月」、「este mes」、「hace 3 meses」、「昨日」
• 見やすく整形された出力 - 整列された表とわかりやすい概要を表示し、生の JSON は表示しません
• 明確なエラーメッセージ - 問題が起きたときは、何を修正すればよいかが正確にわかります

ローカルモデルでも使えますか？

はい。これは MCP サーバーなので、MCP に対応するあらゆるクライアントで使えます。そのクライアントがどのモデルを使うかはクライアント側の選択であり、このサーバーには関係ありません。以下では Claude Desktop、Claude Code、Cursor、VS Code について説明していますが、これらはよく質問されるためです。Ollama や LM Studio を利用するローカル環境など、MCP クライアントを実行できるものなら、どれでも同じように接続できます。

予算データは、クライアントが使用するモデルに送信されます。これが気になる方、Actual を使う多くの方にとっては重要な点ですが、ローカルモデルならデータを自分のマシンにとどめられます。

ChatGPT でも使えますか？

いいえ。その理由はこのサーバーにはありません。ChatGPT のコネクターは、SSE または Streamable HTTP を使用する公開 HTTPS エンドポイント上のリモート MCP サーバーのみを受け付けます。このサーバーのように、手元のマシンで実行されるプロセスを ChatGPT に指定する方法はありません。OpenAI はローカルサーバー用のトンネルを提供していますが、エンタープライズプランに限られています。

利用可能にするには、Actual サーバーをインターネットに公開する必要があります。これは、Actual を利用する多くの方が望むこととは正反対です。Claude Desktop、Claude Code、Cursor、VS Code、Gemini CLI、またはローカルモデルを指定した独自の環境など、ローカルの MCP プロセスを起動できるものなら代わりに使えます。

OpenAI のモデルを使いたい場合は、ローカルで stdio 経由の MCP サーバーを実行できる Codex をご利用ください。オプション 6では、必要なコマンドを 1 つ紹介しています。

前提条件

• Actual Budget サーバーが実行中であること（ローカルまたはリモート）
• 以下のすべての方法で Node.js 22.14 以降が必要です。ただし、デスクトップ拡張機能を除きます（Node.js の要件を参照）。
• デスクトップ拡張機能に必要なのは Claude Desktop だけです。Claude Desktop に付属する Node で実行され、バンドルには対応するすべてのプラットフォーム向けの SQLite バイナリが含まれているため、コンパイルも不要です。Windows 11 で Claude Desktop 2.110.0 を使用し、マシンから Node を削除した状態で確認済みです。

クイックスタート

Claude Desktop では、最も手早い方法は 拡張機能です。編集する設定ファイルも、実行するコマンドもありません。それ以外の場合は、以下を Claude Code または Claude Desktop にコピーしてください。

Install the actual-budget-mcp MCP server from npm (https://github.com/henfrydls/actual-budget-mcp).
Configure it with these credentials:
    - My Actual Budget server: http://localhost:5006
    - Password: YOUR_PASSWORD
    - Budget ID: YOUR_BUDGET_ID

Claude がすべて設定します。

インストール

オプション 1：Claude Desktop 拡張機能（設定ファイル不要）

パッケージ化されたデスクトップ拡張機能を利用できます。インストールすると、Claude Desktop の設定 UI でサーバー URL、パスワード、Sync ID の入力を求められます。パスワードとセッショントークンは、編集が必要な設定ファイルではなく、オペレーティングシステムのキーチェーンに保存されます。

**actual-budget-mcp.mcpb をダウンロード**したら、Claude Desktop を開き、設定 > 拡張機能に移動して、その画面にファイルをドラッグしてください。

Windows では、ドラッグしてインストールしてください。ファイルをダブルクリックすると、Claude Desktop が .mcpb ファイル形式を登録していないため、Windows の「このファイルを開くアプリを選択」ダイアログが表示されます。クリーンインストールした Windows 11 で Claude Desktop 0.14.10 を使用して確認済みです。

拡張機能には必要なものがすべて含まれているため、インストールの進行状況が見えないまま待たされることなく、最初の質問にすぐ回答します。ダウンロードは一度だけで、サイズは大きいですが、進行状況バーが表示されます。

この方法では Node.js をインストールする必要はありません。Claude Desktop に付属する Node で拡張機能を実行します。Windows 11 マシンで Node の名前を変更して使えない状態にしたうえで質問しても、サーバーが起動して回答することを確認しました。

以前のビルドでは、npm からパッケージを起動していました。そのためダウンロードサイズは小さくなりましたが、初回起動時にダウンロードされるようになり、進行状況も表示されませんでした。Claude Desktop は待機した後、サーバーが停止していると判断して接続できないと表示しましたが、数分後に拡張機能が動作し始めました。現在のバンドルには、Actual が対応するすべてのプラットフォーム向けの SQLite バイナリが含まれています。これらは N-API バイナリなので、プラットフォームごとに 1 つあれば、あらゆる Node バージョンで利用でき、起動時に選択する必要もありません。

拡張機能の更新

古いバージョンの上に新しいバージョンをインストールしても、入力済みの設定は保持されます。ただし、実際に確認された例外が 1 つあります。バージョン間でフィールドのタイトルが変わった際、保存済みのサーバーパスワードが消去されました。更新後に Claude が接続できない場合は、ほかを調べる前に拡張機能の設定を開き、パスワードフィールドを確認してください。

オプション 2：Claude Code（コマンド 1 つ）

claude mcp add actual-budget-mcp -e ACTUAL_SERVER_URL=http://localhost:5006 -e ACTUAL_PASSWORD=your-password -e ACTUAL_BUDGET_ID=your-budget-id -- npx -y actual-budget-mcp

オプション 3：Claude Desktop（設定ファイルを編集）

以下を claude_desktop_config.json に追加してください。

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "actual-budget-mcp": {
      "command": "npx",
      "args": ["-y", "actual-budget-mcp"],
      "env": {
        "ACTUAL_SERVER_URL": "http://localhost:5006",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_BUDGET_ID": "your-budget-sync-id"
      }
    }
  }
}

オプション 4：Cursor

ボタンを押すと、プレースホルダー値を使ってインストールされます。その後、Cursor Settings > MCP を開き、3 つの値を置き換えてください。サーバー URL、パスワード、予算の Sync ID です。すべて手動で設定する場合は、Cursor Settings > MCP > Add new MCP server に移動し、以下を追加してください。

{
  "mcpServers": {
    "actual-budget-mcp": {
      "command": "npx",
      "args": ["-y", "actual-budget-mcp"],
      "env": {
        "ACTUAL_SERVER_URL": "http://localhost:5006",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_BUDGET_ID": "your-budget-sync-id"
      }
    }
  }
}

オプション 5：VS Code（GitHub Copilot）

上記と同様に、ボタンでプレースホルダーが入力されるので、あとから 3 つの値を置き換えてください。手動で設定する場合は、VS Code の settings.json に次を追加します。

{
  "mcp": {
    "servers": {
      "actual-budget-mcp": {
        "command": "npx",
        "args": ["-y", "actual-budget-mcp"],
        "env": {
          "ACTUAL_SERVER_URL": "http://localhost:5006",
          "ACTUAL_PASSWORD": "your-password",
          "ACTUAL_BUDGET_ID": "your-budget-sync-id"
        }
      }
    }
  }
}

オプション 6：Codex（OpenAI）

コマンドを 1 つ実行するだけで、~/.codex/config.toml に設定を書き込みます。

codex mcp add actual-budget-mcp \
  --env ACTUAL_SERVER_URL=http://localhost:5006 \
  --env ACTUAL_PASSWORD=your-password \
  --env ACTUAL_BUDGET_ID=your-budget-sync-id \
  -- npx -y actual-budget-mcp

Codex には拡張機能やバンドル形式がないため、この方法が最も手短です。登録後は codex mcp list で確認でき、codex mcp remove actual-budget-mcp で削除できます。

これは、ローカルエージェント、CLI、IDE 拡張機能としての Codex を指します。ブラウザー版の Codex は OpenAI のマシン上で実行されるため、ネットワーク上の Actual サーバーには接続できません。

オプション 7：Docker

このイメージはほかのすべての方法と同様に stdio で通信するため、クライアントがコンテナを起動し、そのライフサイクルを管理します。

{
  "mcpServers": {
    "actual-budget-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--add-host=host.docker.internal:host-gateway",
        "-v", "actual-budget-mcp-data:/data",
        "-e", "ACTUAL_SERVER_URL",
        "-e", "ACTUAL_PASSWORD",
        "-e", "ACTUAL_BUDGET_ID",
        "ghcr.io/henfrydls/actual-budget-mcp:latest"
      ],
      "env": {
        "ACTUAL_SERVER_URL": "http://host.docker.internal:5006",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_BUDGET_ID": "your-budget-sync-id"
      }
    }
  }
}

一度は誰もがつまずく点が 2 つあります。

• コンテナ内の localhost はコンテナ自身を指します。 Actual サーバーはそこにはありません。代わりに host.docker.internal を使うとホストに接続できます（上記の --add-host フラグで名前を解決できるようにします。Linux ではこれが必要です）。
• /data をマウントしてください。 ここには予算のキャッシュが保存されます。ボリュームを使わないと、起動するたびに予算全体をサーバーから再ダウンロードします。

オプション 8：ソースから実行（コントリビューター向け）

git clone https://github.com/henfrydls/actual-budget-mcp.git
cd actual-budget-mcp
npm install
cp .env.example .env   # Edit with your credentials
npm run build
npm run test:connection # Verify it works

セットアップを確認する

--verify は、実行するシェルの環境変数を読み取ります。一方、上記のインストール方法では、認証情報が MCP クライアントの設定に保存されます。そのため、コマンドの実行時に次のように設定してください。

ACTUAL_SERVER_URL=http://localhost:5006 \
ACTUAL_PASSWORD=your-password \
ACTUAL_BUDGET_ID=your-sync-id \
npx -y actual-budget-mcp --verify

サーバーに接続して予算をダウンロードし、見つかった口座数とカテゴリグループ数を表示します。これらの変数を設定せずに実行すると、未設定であることが報告されます。これはコマンドについての報告であり、インストールに関するものではありません。

クライアントの設定を変更した後は、クライアントを再起動してください。 Claude Desktop、Claude Code などは起動時に MCP の設定を読み込むため、再起動するまで変更は反映されません。

数日間連続で実行する場合

ほとんどのクライアントは、起動時にこのサーバーを開始し、終了時に停止するため、以下の内容は関係ありません。常時稼働するチャットボットやサービスなど、プロセスを起動したまま実行する場合は関係します。

サーバーは起動時に予算を一度ダウンロードし、ローカルにコピーを保持します。ツール経由で要求した場合でも、actual://accounts を読み取った場合でも、読み取りの前に毎回、ローカルのコピーにないデータを Actual サーバーから取得します。そのため、Actual アプリで行った編集は、次に質問したときに反映されます。サーバーを再起動する必要も、反映させるために銀行同期を実行する必要もありません。

毎回の呼び出しで通信が発生しないよう、次の3つの制限を設けています。

• 60秒以内に取得したコピーは最新と見なされるため、短時間に質問が続いても同期は1回で済みます。書き込みの前に実行される同期も含め、同期はすべて対象です。
• 読み取りでは、取得を待つ時間は最大20秒です。それを過ぎると、処理が停止する代わりにローカルのコピーを使って回答し、その旨を伝えます。
• 取得に失敗した場合、または期限を過ぎた場合、その後60秒間の読み取りでは、再試行せずローカルのコピーを使って回答します。サーバーがダウンしていると、そうしなければ読み取りのたびに最大待ち時間が発生し、それが続いてしまいます。

Actual サーバーがダウンしている、接続できない、または単に応答が遅いなどの理由でデータを取得できなかった場合、返信の末尾に、更新できなかったこと、数値データの経過時間、問題の内容を示す行が追加されます。

Could not refresh from the Actual server; these figures are from the last
sync, 14 minutes ago. Anything changed in the Actual app since then may be
missing. Reason: The budget's sync state is out of sync with the Actual
server, so no operation can run until it is repaired. Run the `repair_sync`
tool to rebuild the sync state (non-destructive), or repair it in the Actual
app under Settings > Show advanced settings.

この行が重要です。そうしなければ、サーバーがダウンしたときに、何時間も前の数値データで回答し続けても、それがいつのものか分かりません。問題の理由も表示されます。理由によって必要な対応が異なるためです。ネットワークの瞬断なら自然に解消しますが、同期が取れていない予算は修復が必要で、ログインを拒否された場合は認証情報を確認する必要があります。

書き込みには影響しません。書き込みでは、書き込みの可否を判断するチェックの前にすでにデータを取得するため、追加の取得は発生しません。

各クライアントには、それぞれ独自の ACTUAL_DATA_DIR が必要です。複数のプロセスで同じローカルコピーを共有すると、データが破損します。長時間稼働するサーバーでは、別のクライアントが同じコピーを誤って参照しやすくなります。サーバーが一日中稼働しているためです。

設定

変数	必須	説明
ACTUAL_SERVER_URL	はい	Actual Budget サーバーの URL。使用する URL とポートを参照してください
ACTUAL_PASSWORD	はい*	サーバーのパスワード（Actual Budget の［Settings］で設定します）。*ACTUAL_SESSION_TOKEN を使う場合は不要です
ACTUAL_SESSION_TOKEN	いいえ	パスワードがない OIDC 対応サーバー向けです。ACTUAL_PASSWORD の代わりに使用してください。両方が設定されている場合は、トークンが優先されます
ACTUAL_BUDGET_ID	はい	予算の Sync ID（［Settings］>［Show advanced settings］で確認できます）
ACTUAL_ENCRYPTION_PASSWORD	いいえ	予算ファイルが暗号化されている場合にのみ必要です
ACTUAL_DATA_DIR	いいえ	予算キャッシュの保存先です。既定では OS のデータディレクトリです（以下を参照）
ACTUAL_READ_ONLY	いいえ	読み取り専用で実行するには 1／true／yes に設定します。安全性を参照してください
ACTUAL_TOOLSET	いいえ	chat を指定すると、全44個ではなく日常的に使う18個のツールを利用できます。既定値は full です。ツールセットの選択を参照してください

セッショントークンを使う（OIDC サーバー）

Actual サーバーが OIDC 経由でサインインする場合、ACTUAL_PASSWORD に設定するパスワードはありません。代わりにサーバーがセッショントークンを発行します。ACTUAL_SESSION_TOKEN にそのトークンを設定し、パスワードは未設定のままにしてください。

トークンを確認するには、Actual にサインインしているブラウザーで次の操作を行います。

1. ブラウザーの開発者ツールを開きます
2. Application（Chrome／Edge）または Storage（Firefox）を開きます
3. IndexedDB → actual データベース → asyncStorage ストアを展開します
4. user-token キーの値をコピーします

トークンは Local Storage ではなく IndexedDB に保存されます。そのため、Local Storage を確認しても見つからないことがよくあります。

このトークンはパスワードと同様に扱ってください。同じアクセス権限が付与されます。また、有効期限があります。期限が切れると、サーバーはその旨を伝え、新しいトークンを発行するよう案内します。存在しないパスワードの入力ミスとして扱われることはありません。

URL とポートの選び方

Actual の実行方法によって異なります。間違った URL を選ぶと、原因のわからない接続エラーになります。

Actual の実行方法	URL
セルフホスト型同期サーバー（Docker、VPS など）	http://localhost:5006、またはホスト先の URL
デスクトップアプリ	http://localhost:5007

デスクトップアプリはポート 5007 で独自の同期サーバーを実行し、アプリが開いている間だけ稼働します。アプリを閉じるとリッスンするプロセスがなくなるため、サーバーは接続できません。

この組み込みサーバーは 127.0.0.1 のみでバインドされます。同じマシンからはアクセスできますが、それ以外からはアクセスできません。そのため、Claude がアプリのあるマシン以外（別のコンピューターや仮想マシンなど）で実行される場合は、SSH トンネルまたはポートフォワードが必要です。ホストの LAN アドレスを指定しても機能しません。

キャッシュの保存場所

ACTUAL_DATA_DIR を設定しない場合、予算のキャッシュはシステム標準のデータディレクトリに保存されます。

OS	デフォルトの保存場所
Linux	$XDG_DATA_HOME/actual-budget-mcp、または ~/.local/share/actual-budget-mcp
macOS	~/Library/Application Support/actual-budget-mcp
Windows	%APPDATA%\actual-budget-mcp

これはキャッシュであり、データそのものではありません。削除すると、次回の実行時にダウンロードし直すだけです。再起動で削除され、次回の起動時に予算全体を再ダウンロードすることがないよう、意図的に一時ディレクトリの外に保存されます。

予算 ID の確認方法

1. Actual Budget を開きます
2. Settings を開きます。予算名の横にある矢印をクリックするか、サイドバーで More、次に Settings を選択します
3. Show advanced settings をクリックします
4. Sync ID をコピーします

Budget ID ではなく、Sync ID を使ってください。 Actual には両方が上下に表示され、どちらも UUID です。変数名にかかわらず、ACTUAL_BUDGET_ID に設定するのは Sync ID と表示されているほうです。もう一方を使うと Budget "..." not found on the server が表示され、値が単に別の項目のものだったのに、入力を間違えたように見えてしまいます。

Sync ID が (none) と表示される場合、その予算はサーバーに一度も同期されていません。このサーバーは同期サーバー経由で Actual と通信するため、ローカルのみに保存されている予算は、同期するまで使用できません。

プライバシーポリシー

データ収集。 このサーバーはデータを一切収集しません。テレメトリ、分析、使用状況の報告はなく、今後導入する予定もありません。個人の財務情報を読み取るツールが、外部に情報を送信するべきではないからです。アカウントを作成する必要はなく、オプトアウトするものもありません。

使用方法と保存。 サーバーが通信するのは、設定した URL の Actual Budget サーバーだけです。予算データは、キャッシュの保存場所に記載されているデータディレクトリ内に、使用しているマシン上でキャッシュされます。そのため、起動するたびにダウンロードする必要はありません。それ以外の場所には何も書き込まれません。

認証情報はこのサーバーではなく、MCP クライアントが処理します。Claude Desktop はパスワードとセッショントークンをオペレーティングシステムのキーチェーンに保存します。サーバーは起動時に環境変数としてそれらを受け取り、接続に使用しますが、ディスクには一切書き込みません。

第三者との共有。 ありません。作成者、分析サービス、その他の第三者にデータが送信されることはありません。サーバーが開くネットワーク接続は、お使いの Actual サーバーとの接続だけです。

あわせて明記しておくべきことが二つあります。お使いのモデル（Claude、または使用するクライアント）が、問い合わせた予算データを必然的に参照しますが、その取り扱いには各プロバイダー独自の規約が適用されます。また、npx を使ってインストールすると、npm からパッケージがダウンロードされます。これは通常のパッケージのダウンロードであり、予算データは関与しません。

データの保持。 キャッシュは削除するまでお使いのマシンに保存されます。キャッシュは Actual サーバー上のデータのコピーなので、削除してもデータは失われません。次回の実行時に再びダウンロードされます。サーバーをアンインストールしても、そのディレクトリだけが残ります。ディレクトリは削除できます。

お問い合わせ。 https://github.com/henfrydls/actual-budget-mcp/issues で issue を作成してください。ポリシー全文は https://actual-mcp.henfrydls.com/privacy/ にも掲載されています。

このサーバーが書き込む取引には、サーバーが生成した ID が付与されます

このサーバーを通じて作成されるすべての取引、分割、振替には、送信前に UUID が付与されます。書き込みでエラーが報告された場合、サーバーはその ID を使って該当する行を再度特定します。この ID は取引自体の id であり、imported_id ではありません。そのため、インポートしたファイルに対する Actual の重複排除は、他の行と同様に引き続き機能します。

この仕組みは Actual 上では見えず、お使いの操作にも影響しません。同じ取引を手動で書き込む場合との実際の違いであるため、記載しています。

安全性

あいまいな指示を受けたエージェントが予算データを変更しないよう、三つの仕組みで保護しています。

削除ツールは削除前にプレビューを表示します

すべての削除ツールは、最初の呼び出しでは何も削除しません。削除される内容を報告して、その時点で処理を止めます。削除するには、もう一度、明示的に呼び出す必要があります。

delete_category(category: "Groceries")
  → preview: transactions affected, budget and rollover warning. Nothing deleted.

delete_category(category: "Groceries", confirm: true, confirm_name: "Groceries")
  → deleted

プレビューには、削除できるすべての行が表示されます。今日より後の日付の行、予算内で他の行より古い行、分割取引の一部、閉鎖済み口座の行も対象です。以前は、この四つのケースでプレビューが空白のまま削除されていたため、確認を求めても、何も表示されていませんでした。どの取引にも一致しない ID は、削除済みとして報告するのではなく、拒否されるようになりました。

名前で対象を特定するツール（delete_account、delete_category、delete_category_group、delete_payee）には、名前を完全一致で指定する confirm_name も必要です。誤った項目の削除は、実際にはこの方法で起こります。「Adicionales」を指定すると、「Ingresos Adicionales」が選ばれることがあるためです。正確な ID を受け取るツール（delete_transaction、delete_rule）では、confirm: true だけが必要です。

既存の取引は二重に作成されません

create_transaction は書き込む前に確認します。勘定科目、日付、金額のすべてが予算内の既存の取引と一致する場合、新しい取引は作成せず、該当する取引を表示します。

create_transaction(account: "Checking", amount: -50, date: "2026-06-05")
  → A transaction like this one already exists, so nothing was created:

      2026-06-05  -50.00  Checking  Claro
        id: 0b6d516e-...

    Same account, same date, same amount. If this is a second, genuine payment
    rather than the same one recorded twice, call again with allow_duplicate: true.

create_transaction(account: "Checking", amount: -50, date: "2026-06-05", allow_duplicate: true)
  → Transaction created

同じ日に、同じカードで同じコーヒーを2回購入することは実際にあり得るため、このフラグが用意されています。追加で必要なのは呼び出し1回分だけです。これは0.9.xからの変更です。0.9.xでは、2回目の呼び出しで何も通知されないまま2行目が作成されていました。

確認の前に同期するため、別のクライアントが書き込んだ内容も確認できます。このクライアントが書き込んだ内容だけを確認するわけではありません。これは、同じ予算を使う2つのエージェントが互いの変更を確認できない場合に備えたものです。同じ理由から、reconcile_currency_residual でも同じフラグを受け取り、残高の読み取りと計算の前に同期します。

エラーとして返されるわけではありません。 削除ツールは、プレビューに isError を設定することで、繰り返し呼び出しても誤って何かが削除されないようにしています。このツールでは意図的に逆の動作をします。繰り返し呼び出されても何も作成されません。isError を確認するエージェントは、要求が拒否されたと判断して再試行し、それが重複を生みます。削除ではフラグを設定しますが、このツールでは設定しません。

コストについて。 重複が見つかるかどうかにかかわらず、create_transaction の呼び出しごとにラウンドトリップが1回増えます。同じマシン上のサーバーであれば、測定できるほどの差はありません。リモートサーバーの場合、書き込みにかかる時間はおよそ2倍になります。ラウンドトリップのレイテンシが80 msの場合、単一の作成処理では87 msから171 msになり、連続する22件の作成処理では1.9 sから3.8 sになります。allow_duplicate: true を渡すと、確認だけでなく同期も省略されるため、すでに別の場所で重複排除済みの一括インポートではコストがかかりません。

オフライン時とサーバーが応答しない場合。 同期に失敗しても、ローカルコピーに対して確認を行い、書き込みはブロックされません。そのため、オフラインのセッションでも、確認の精度は下がりますが書き込みを続けられます。確認精度が下がったことは、理由とともに stderr に出力されるため、通知なしに確認が不完全になることはありません。

接続を受け入れた後、サーバーが応答しない場合は、以前は処理に時間がかかっていました。Actual ライブラリには独自のタイムアウトが設定されていないため、Node の5分間のヘッダータイムアウトに達するまで待機していました。書き込みの前と後の2か所で発生する可能性があります。以下の ACTUAL_HTTP_TIMEOUT_MS により、デフォルトで60秒後に待機を終了するようになりました（#99）。

検出できないケースは次のとおりです。

• 行の保存時に金額または日付を書き換えるルールが適用された場合です。保存された行が、指定した内容と一致しなくなるためです。よくある種類である、名前を変更するルールには影響されません。
• 確認と書き込みの間に取引が追加された場合です。同期によってその時間は短くなりますが、なくなるわけではありません。これは書き込む前に確認しますが、両方を同時に行うわけではありません。
• まだ確認処理を実行しない create_transfer と create_split_transaction、および create_account による開始残高です。#98 で追跡しています。

reconcile_currency_residual と、クリア済みとしてマークされていない行

今日までの勘定科目内のすべての取引と比較します。この動作は以前から変わっていません。銀行の取引明細には通常、計上済みの項目だけが表示されます。そのため、勘定科目に確認されていない行が残っている場合、比較する2つの数値が同じ対象を示していない可能性があります。

この判断を代わりに行うことはありません。その状況を報告します。

Currency residual reconciled:
  Account:    Card (USD)
  Was:        -120.00
    includes 1 row not marked cleared, -20.00
    cleared rows alone come to -100.00, and against that
    figure the adjustment would have been 100.00.
    Check which of the two the balance you gave is measuring.
  Target:     0.00
  Adjustment: 120.00

すべての行がクリア済みとしてマークされている場合は、何も表示されません。

クリア済みの行だけを比較対象にする案も検討し、まず実際の予算で検証しました。クリア済みとしてマークされていない行の多くは数週間前から残っており、銀行に由来するものはありませんでした。数日で処理される途中の項目ではなく、誰も確認していなかった行でした。クリア済みの金額と照合していたら、それらすべてが残差カテゴリへの調整として計上されるところでした。これは、この機能が防ごうとしている問題を別の形で引き起こします。そのため、数値はそのままにして、両方の数値を表示します。

書き込みを行わない reconcile_account も同じ2つの数値を読み取り、balance_counts を使ってどちらを採用するか選択します。

reconcile_currency_residual と日付

書き込む調整の未来の日付は受け付けません。このツールの目的は、口座を銀行が現在報告している残高に合わせることです。後日有効になる行では、それを実現できません。また、正しく動作させることもできませんでした。残高には今日までの取引が反映されるため、未来の日付の調整は残高に反映されず、実行のたびに別の調整が計上されていました。

ここでいう「今日」とは、サーバーの今日です。サーバーより先のタイムゾーンにいるクライアントには、クライアント側の今日が未来だと判定されることがあります。date を省略するか、"today" を渡すと、チェックと同じ時計が使われるため、常に機能します。create_transaction にはこの制限がないので、カードで週末にした購入が翌営業日に計上される場合に必要となる、未来の日付での購入記録も引き続き行えます。

口座に今日より後の日付の取引がある場合、それらをどう扱うか確認します。 Actual の残高は今日までを対象としますが、銀行の金額はそうとは限りません。週末のカード購入は、翌営業日の日付で計上されることがよくあります。そのため、銀行ではすでに反映されていても残高には反映されていない項目が生じ、そうでなければ差額が為替差異として計上されてしまいます。

そのため reconcile は該当する行を報告し、どの見方をしたかを指定するまで何も計上しません。

reconcile_currency_residual(account: "Card", target_balance: -140, category: "Cashback")
  → No adjustment was booked for Card.

    This account holds 2 transactions dated after today, so the balance Actual
    reports and the balance your bank reports are not measuring the same thing.

      2026-09-28  -40.00  WEEKEND-PURCHASE  (came from the bank, so the bank counts it)
      2026-10-26  -80.00  SCHEDULED-LATER

      Balance to today:        -100.00
      Those rows come to:      -120.00
      Balance counting them:   -220.00
      You said the bank says:  -140.00

    Which is it?

      future_rows: "exclude"   the bank has not posted them yet.
                               Adjustment would be -40.00.
      future_rows: "include"   the bank has posted them already, ...
                               Adjustment would be 80.00.

どの見方をするかは、一般には行が何を表すかを示すものがないため、ユーザーが選びます。判断できる情報がある場合は、その旨が示されます。銀行から取り込まれた行は、当然ながら銀行が反映しているものです。また、ここで入力され、まだ照合されていない行は、銀行がまだ把握していない可能性があります。どちらも決め手にはなりませんが、判断材料にはなります。行は古い順に並ぶため、計上された可能性が最も高い、最も近い日付の行から確認できます。

今日より後の日付の行がない口座には影響せず、確認も表示されません。今日と同じ日付の行は、残高にすでに含まれているため、未来の日付ではなく現在のものとして扱われます。

どちらを選んだかは、調整自体に FX residual adjustment (counting 2 transactions dated after today) のように記録されます。そのため、後から誤った見方で計上した行を特定でき、謎を解く必要がなくなります。

この機能が存在する前の例を示します。今日までの口座残高が -100.00、銀行が計上済みの未来日付の購入が -40.00、銀行がまだ計上していない後日予定の振替が -80.00、銀行の金額が -140.00 でした。-40.00 が計上され、口座の合計は -260.00 となりましたが、銀行の残高は -220.00 でした。この調整は、購入額そのものを「為替差異」とするカテゴリに二重で記録したものでした。

また、2026-09-31 や 2026-02-30 のような存在しない日付は、未来の日付と見なさず拒否します。他のツールは今もあり得ない日付を受け付け、そのまま保存しますが、これは以前からの動作であり、変更ありません。

また、正常に処理される場合でも同期が3回行われます。残高を読み取る前に1回、委譲先の create 内で1回、プッシュのために1回です。このうち2回は連続したプルであるため、リモートサーバーへの不要な往復が発生します。

読み取り専用モード

ACTUAL_READ_ONLY=1 を設定すると、サーバーでは読み取り、分析、修復用の17個のツールのみが公開されます。書き込みツールは登録すらされないため、ツールの検出にも現れず、エージェントは見えないものを呼び出すよう説得されることもありません。

repair_sync は意図的に利用可能なままにしています。予算データではなく同期状態を修復するものであり、非表示にすると同期がずれた予算を復旧する方法がなくなるためです。

書き込みはデフォルトで有効です。読み取り専用はオプトインです。

ツールセットの選択

各接続では、何かを尋ねる前にツールリスト全体が送信されます。実際のツールを登録し、実際のクライアントに tools/list を要求する scripts/measure-toolset.mjs で測定した結果は次のとおりです。

ACTUAL_TOOLSET	ツール数	tools/list
full (default)	44	39.7 KiB
chat	18	17.4 KiB
ACTUAL_READ_ONLY=1 を指定した chat	8	5.7 KiB
ACTUAL_READ_ONLY=1 を指定した full	17	12.4 KiB

chat は日常的に使うセットです。予算の確認、取引の記録と分類、予算化した資金のカテゴリ間での移動ができます。含まれないのは、予算の設定と修復です。つまり、アカウント、カテゴリ、グループ、受取人、ルールの作成と削除に加え、reconcile_currency_residual と repair_sync が対象外です。

設定する価値がある理由は2つあります。より重要なのは2つ目ですが、会話の内容にかかわらずコンテキストは消費され、44個の説明から選ぶモデルは、18個から選ぶモデルよりも誤ったツールを選びやすくなります。

プロンプトは、呼び出すツールと組み合わせて提供されます。それぞれ、3つか4つのツールを指定する短いスクリプトであるため、利用できないツールを使うプロンプトも提供されません。chat ではプロンプトが1つも残りません。また、プロンプトのないサーバーはプロンプトを一切公開しないため、prompts/list は空のリストではなく、このメソッドがサポートされていないと応答します。

2つの設定は互いに競合せず、対象を絞り込みます。読み取り専用設定は存在するツールを決め、ACTUAL_TOOLSET はそのうち提供するツールを決めます。

ツール（44）

読み取り（11）

ツール	説明	プロンプトの例
list_accounts	残高を含むすべての口座	「すべての口座を表示してください」
get_budget_month	指定した月の予算	「3月の予算はどのような状況ですか？」
get_transactions	条件で絞り込んだ取引	「先週の5,000を超える取引を表示してください」
get_category_balance	複数月にわたるカテゴリの推移	「6月までの3か月間、食費はどのような状況でしたか？」
get_budget_summary	予算の概要	「2月の予算概要を教えてください」
get_categories	すべてのカテゴリグループとカテゴリ。非表示のものは include_hidden で指定します	「どのようなカテゴリがありますか？」
get_payees	予算内のすべての支払先	「すべての支払先を一覧表示してください」
get_schedules	定期支払い：次回の支払予定、金額、前回分が記帳されたかどうか	「今後どのような請求がありますか？」
reconcile_account	口座残高と銀行の金額を照合し、差額の理由を説明します	「当座預金の明細には12,500.00とあります。何が足りないのでしょうか？」
get_rules	すべての取引ルール	「ルールを表示してください」
balance_history	口座残高の推移	「当座預金口座の残高推移を表示してください」

パラメーター

get_budget_month - month（任意）：YYYY-MM または自然言語（「今月」「先月」「enero 2025」）

reconcile_account - account（必須） | expected_balance（必須）：銀行が示す金額 | as_of（任意）：その金額の基準日。既定値は今日です。この日付より後の取引はカウントされません | balance_counts（任意）：all（既定値）は未決済の行もカウントし、cleared_only はカウントしません | lookback_days（任意、既定値は90）。読み取り専用で、記帳は行いません。差額の理由として考えられるものを、可能性の高い順に列挙します。二重に入力された請求、別の口座にある金額、締め日より後の日付が付いた行、最後に金額だけが一致するものです。組み合わせは意図的に検索しません。通常の口座では、いくつかの金額を足すと、ほとんどどのような切りのよい金額にもなるためです。理由が見つからない場合は、その旨を伝えます。

get_transactions - account（任意）：口座名 | start_date / end_date（任意）：YYYY-MM-DD または自然言語 | category（任意）：カテゴリ名（名前の一部でも一致）またはカテゴリID全体 | payee（任意）：支払先名 | min_amount / max_amount（任意）：金額で絞り込み | notes_contains（任意）：メモから検索するテキスト。大文字と小文字は区別されません。取引が属する分割行のメモも検索します。期間を指定しない場合はすべての日付を検索します | uncategorized（任意）：カテゴリのない取引のみ。分割取引の親行、予算内の同じ側にある口座間の振替、予算対象外の口座は除外されます。期間を指定しない場合はすべての日付を検索します | limit（任意、既定値は50）

get_category_balance - category（必須）：カテゴリ名またはID | months（任意、既定値は3）：期間の月数。既定値はあくまで既定値であり、上限ではありません | month（任意）：期間の終了月。既定値は今月です。過去の期間も直接指定できます

get_budget_summary - month（任意）：YYYY-MM または自然言語。予算が設定されていないグループには割合が表示されません。0以下の予算に対する割合には適切な解釈がないため、その行には状況が表示されます。

balance_history - account（必須）：口座名またはID | start_date（任意、既定値は3か月前） | end_date（任意、既定値は今日）

### 分析（5）

ツール	説明	プロンプトの例
budget_vs_actual	カテゴリーごとの予算額と支出額	「今月、予算を超えているものはありますか？」
spending_projection	月末の支出予測	「今月は予算内に収まりそうですか？」
category_trends	期間内の月ごとの支出傾向	「6月までの6か月間、支出はどのように推移しましたか？」
spending_by_category	カテゴリー別の支出内訳	「2月のカテゴリー別支出を表示してください」
monthly_summary	収入、支出、貯蓄の比較	「過去3か月間の家計はどうでしたか？」

パラメーター

budget_vs_actual - 月の純額がプラスのカテゴリーは、予算内としてではなく収入として扱われ、予算内の合計から除外されます。month（任意）：YYYY-MM または自然言語 | group（任意）：カテゴリーグループで絞り込み

spending_projection - 入ってくるお金は支出として予測されません。また、見出しの件数には、予算がまったく設定されていないカテゴリーも含め、すでに予算を超えているカテゴリーが含まれます。month（任意）：YYYY-MM または自然言語

category_trends - category（任意）：特定のカテゴリー。省略した場合は支出額上位のカテゴリー | months（任意、デフォルトは6）：対象期間の月数。デフォルトは初期値であり、上限ではありません | month（任意）：対象期間の最終月。デフォルトは今月です。予算ファイルより前の月は、呼び出しを終了するのではなく、応答内で示されます

spending_by_category - start_date / end_date（任意）：日付範囲 | include_income（任意、デフォルトはfalse） | limit（任意、デフォルトは20）。分割取引の各部分はそれぞれのカテゴリーに計上され、予算対象外の口座は除外されます。月次照合と同じ合計が使われます。割合の列は支出に占める割合です。そのため、期間の純額がプラスのカテゴリー（返金や払い戻しなど）も表示されますが、割合は付きません。フッターでは支出、収入、純額が分けて表示されます。そうでない場合、収入の行が1つあるだけで分母が小さくなり、割合の合計が100%を超えることがあります。

monthly_summary - months（任意、デフォルトは3）：表示する月数

書き込み：取引（11）

ツール	説明	プロンプトの例
create_transaction	新しい取引を追加	「今日、Walletから食料品に500使いました」
create_transactions	複数の取引を一度に追加。すべて成功するか、すべて取り消されます	「18日のこの22件の入出金を記録してください」
create_split_transaction	1件の支払いを複数のカテゴリーに分割	「あの3,000の支払いを分けてください。食料品に2,000、日用品に1,000」
update_transaction	既存の取引を編集	「あの取引の金額を600に変更してください」
delete_transaction	取引を削除（まずプレビューします。安全性を参照）	「あのテスト取引を削除してください」
update_budget_amount	予算額を設定、または増額	「今月のHealthに10,000追加してください」
transfer_between_categories	取引を作成せずに、予算額をカテゴリー間で移動	「Pending RefundsからFamilyに125.50移動してください」
hold_for_next_month	その月の未割り当て金額の一部を翌月に繰り越す	「残額のうち5,000を来月に繰り越してください」
set_category_carryover	カテゴリーの超過支出を最初から差し引くのではなく、翌月に繰り越す	「今後、Groceriesの超過分を独自に繰り越すようにしてください」
recategorize_transaction	別のカテゴリーに移動	「あの取引をEntertainmentに移動してください」
create_transfer	口座間で送金	「CheckingからSavingsに10,000送金してください」
reconcile_currency_residual	累積した為替レートの端数を解消	「USDカードを250.00 USDに照合してください」
run_bank_sync	リンク済みの銀行と同期	「銀行取引を同期してください」

パラメーター

**create_transactions** - `transactions`（必須）：`{account, amount, payee?, category?, date?, notes?, cleared?, imported_id?}` の配列 | `allow_duplicate`（任意）。**複数件を記録する場合は、こちらを使います。** 書き込みを行う前にすべての行を解決して検証します。使用できない行が1つでもある場合、何も作成されません。返信には、失敗した行とその理由を示し、残りの行も問題はなかったものの書き込まれなかったことを記載します。これに置き換わるのは、`create_transaction` を何度も並列で呼び出す方法です。一度に9件呼び出すとサーバーがダウンしたことから、この上限が判明しました。ペイ先に自分の口座を指定した行は、`create_transaction` と同じルールで振替になります。返信の末尾には、そのような行の一覧と、それぞれが予算に与えた影響が記載されます。カードの支払いを両方の明細で読み取った場合のように、1つの資金移動の両側にあたる2行は、同じ資金移動を二重に記録するものとして拒否されます。相手側の口座にすでにインポートされている振替も同様です。カードの明細に口座名ではなく「PAYMENT RECEIVED」のように記載されている場合や、異なる銀行間でよくあるように、2つの銀行への計上が**1日ずれている**場合も対象です。2日ずれている場合は、別々の資金移動として扱われます。異なる日に同じ口座から同額を支払った2件は影響を受けません。この比較では引き続き日付を厳密に照合します。`imported_id` がすでに予算に存在する行は拒否されるため、バッチを再送信しても重複しません。

create_transaction - account（必須）：口座名 | amount（必須）：支出は負の値、収入は正の値 | payee（任意）：自分の口座名を指定すると振替になり、相手側の口座にも対応する行が作成されます | category（任意）：カテゴリを指定すると、通常の買い物として扱われ、振替にはなりません。ただし、両方の口座が予算内にある場合に限ります。これは、店の名前が口座名と同じ場合に使います。どちらかの口座が予算外の場合は、予算の境界をまたいで資金が移動するため、振替のままになります | date（任意） | notes（任意） | cleared（任意） | allow_duplicate（任意）：同じ口座、日付、金額の取引が存在していても作成します

update_transaction - transaction_id（必須） | amount、payee、category、date、notes、cleared（すべて任意）

delete_transaction - transaction_id（必須） | confirm（任意）：削除するには true を指定する必要があります。指定しない場合、ツールはプレビューのみを行います

update_budget_amount - category（必須） | amount（必須） | month（任意） | mode（任意）：absolute（既定値）は予算額を設定し、delta は既存の金額に加算します。負の値も指定できます。通常の調整には delta を使います。繰り越しや支出がある場合、絶対額を設定するにはまず 24,545.50 のような数値を算出する必要があり、その数値だけでは計算が誤っていても分かりません。

transfer_between_categories - from（必須）：移動元のカテゴリ | to（必須）：移動先のカテゴリ | amount（必須）：正の値 | month（任意、既定値は当月）。どちらか一方でも収入カテゴリの場合、YYYY-MM 形式ではない月を指定した場合（月は 01 から 12 の範囲）、または同じカテゴリへの移動の場合は拒否されます。Actual 標準のハンドラーはこの3つをすべて受け付け、資金を黙って失わせたり、破棄したり、作り出したりします。収入カテゴリはカテゴリごとに Actual が指定するため、支出グループ内に含まれていることがあります。超過支出のあるカテゴリを補填することは許可され、結果にも記載されます。

hold_for_next_month - amount（必須）：現在保留されている金額に加算します。0 を指定すると保留全体を解除します | month（任意、既定値は当月）。Actual 標準の呼び出しは設定ではなく加算を行い、通知なしにその月の金額を保留するため、返信には保留額の合計が記載されます。また、要求された額より少ない金額しか保留できなかった場合、またはまったく保留できなかった場合も通知されます。四捨五入するとゼロになる金額は、保留解除として扱うのではなく拒否されます。封筒式予算のみ対応します。トラッキング予算には割り当てる資金がないため、保留もできません。 set_category_carryover - category（必須）| enabled（必須）| month（省略可。デフォルトは現在の月）。1か月だけではありません。Actual は、指定された月から作成済みの最後の月まで、すべての月にフラグを書き込みます。そのため、応答では変更された月と、フラグが適用された最後の月が示されます。また、後から作成される月にはフラグが引き継がれないことも説明されます。最後の月は Actual の API で一覧表示も読み取りもできないため、フラグは書き込まれますが、応答では確認できなかったことが示されます。繰り越す超過支出がない収入カテゴリと、繰り越し先となるエンベロープがないトラッキング予算では拒否されます。

recategorize_transaction - transaction_id（必須）| category（必須）

create_transfer - from_account（必須）| to_account（必須）| amount（必須）| date（省略可）| notes（省略可）

create_split_transaction - account（必須）| amount（必須）：合計額。分割額の合計と一致する必要があります | splits（必須）：2つ以上の {category, amount, notes} | payee、date、notes、cleared（すべて省略可）

reconcile_currency_residual - 今日までのすべての行と照合し、その金額のうち消込済みとしてマークされていない額と、それがなかった場合の調整額を示します。account（必須）| category（必須）：調整を計上する先 | target_balance（省略可。デフォルトは 0）| payee、notes（省略可）| date（省略可。今日以前。未来の日付は拒否されます）| allow_duplicate（省略可）：同じ日に同額の取引がすでにあっても計上する | future_rows（省略可）：exclude または include。指定した残高に今日より後の日付の取引がすでに含まれているかどうか

run_bank_sync - account（省略可）：特定の口座を同期します。省略するとすべての口座を同期します

書き込み：カテゴリ（6）

ツール	説明	プロンプトの例
create_category	新しいカテゴリを作成します	"Variable Spending に Gym というカテゴリを作成して"
update_category	カテゴリの名前を変更するか、非表示にします	"Gym を Fitness に変更して"
delete_category	カテゴリを削除します（最初にプレビューします。Safety を参照）	"Fitness カテゴリを削除して"
create_category_group	新しいグループを作成します	"Health というカテゴリグループを作成して"
update_category_group	グループの名前を変更するか、非表示にします	"Health グループを Wellness に変更して"
delete_category_group	グループを削除します（最初にプレビューします。Safety を参照）	"Wellness グループを削除して"

パラメーター

create_category - name（必須）| group（必須）：グループ名または ID

update_category - category（必須）：名前または ID | name（省略可）：新しい名前 | hidden（省略可）：true/false

delete_category - category（必須）| transfer_to（省略可）：取引の移動先カテゴリ | confirm + confirm_name（削除に必須）

create_category_group - name（必須）

update_category_group - group（必須）：名前または ID | name（省略可）：新しい名前 | hidden（省略可）：true/false

delete_category_group - group（必須）| transfer_to：孤立する取引の移動先カテゴリ。グループが空でない場合は必須 | confirm + confirm_name（削除に必須）

### 書き込み：支払先とルール（5）

ツール	説明	プロンプトの例
create_payee	新しい支払先を作成します	「Netflixという支払先を作成して」
update_payee	支払先の名前を変更します	「NetflixをNetflix Premiumに変更して」
delete_payee	支払先を削除します（最初にプレビューします。詳しくは安全性をご覧ください）	「Netflix Premiumの支払先を削除して」
create_rule	取引ルールを作成します	「Amazonが支払先の場合、カテゴリをショッピングに設定するルールを作成して」
delete_rule	ルールを削除します（最初にプレビューします。詳しくは安全性をご覧ください）	「そのルールを削除して」

パラメーター

create_payee - name（必須）

update_payee - payee（必須）：名前またはID | name（必須）：新しい名前

delete_payee - payee（必須）：名前またはID | confirm + confirm_name（削除に必須）

create_rule - condition_field（必須）：payee、payee_name、category、category_group、account、amount、notes、imported_payee | condition_op（必須）：is、isNot、oneOf、notOneOf、contains、gt、ltなど。oneOfとnotOneOfにはリストを指定しますが、payee、category、category_group、account、payee_name、imported_payeeでのみ使用できます | condition_value（必須）：payeeまたはcategoryの場合、名前またはID | action_field（必須）：category、payee、notes、account | action_value（必須）：payee、category、accountの場合、すでに存在する名前またはID。accountを設定すると取引が移動しますが、後で同じ移動をインポートしても認識されないため、銀行の同期で重複が発生することがあります。また、予算対象外に移動した行はカテゴリを失います | stage（任意）。payee、category、category_group、accountに対するcontains、doesNotContain、matchesは拒否されます。ActualではこれらがIDとして保存されるため、比較はIDに対して実行され、誤った取引にルールが適用されます。テキストの場合、imported_payeeには、銀行またはここで作成したユーザーから行が届いたときのテキストが保持されます。見たことのない店での最初の請求を検出するのはこのフィールドです。payee_nameは支払先の現在の名前と比較しますが、その支払先がすでに存在する場合に限られるため、最初の請求は検出できません。両方の方法で検証済みです。get_rulesはすべてのIDフィールドを名前に変換して読み戻し、リストも含めて表示します。また、すでに逆の方法で保存されているルールと、IDが必要な箇所に名前が入っているルールにも印を付けます。後者のルールは適用されません。

delete_rule - rule_id（必須）| confirm（削除に必須）

### Write：口座（3）

ツール	説明	プロンプトの例
create_account	予算内または予算外の口座を作成します	「Family Investment という名前で、10,000 の予算外口座を作成して」
delete_account	口座とその履歴を削除します	「ZZ Test 口座を削除して」
update_account	口座の名前を変更します	「Main Checking を Everyday Account に変更して」

delete_account には2つのキーが必要です。 口座の取引履歴全体が削除されるため、1回の呼び出しで削除されることはありません。最初の呼び出しでは、失われる内容（名前、残高、取引件数）をプレビューするだけで、履歴を保持したまま口座を無効化できるため、代わりに口座を閉鎖することを提案します。実際に削除するには、confirm: true と、口座の正確な名前を設定した confirm_name を指定して、もう一度呼び出してください。削除を拒否する場合、ツールは isError: true を返すため、確認を求めるプロンプトが削除完了と誤認されることはありません。

パラメーター

create_account - name（必須） | offBudget（任意、デフォルトは false） | initialBalance（任意）：人間向けの金額。「Starting Balance」取引を作成します。（Actual のモデルでは口座を予算内または予算外としてのみ扱うため、口座に type はありません。）

update_account - account（必須）：名前または ID | name（必須）：新しい名前。名前の変更のみを行います。予算のステータス（offbudget）と口座の閉鎖は意図的に公開していません。口座を予算に追加または予算から除外すると、すべての月の合計が一度に変わり、口座の閉鎖には、残高の振り分け先を尋ねるアプリ内の専用フローがあるためです。他の口座ですでに使われている名前への変更は拒否されます。Actual では同じ名前を使用でき、その場合、どちらの口座も名前で特定できなくなるためです。

delete_account - account（必須）：名前または ID | confirm（削除する場合は必須）：true にする必要があります | confirm_name（削除する場合は必須）：口座の正確な名前

メンテナンス（1）

ツール	説明	プロンプトの例
repair_sync	同期がずれた予算を修復します	「同期を修復して。すべて失敗している」

同期エラーでツールが失敗し始めた場合、予算の同期状態がサーバーと一致していません。repair_sync は予算データに触れずに、その状態を再構築します。ローカルの ACTUAL_DATA_DIR を削除しても問題は解決しません。不整合はキャッシュではなく、同期状態にあるためです。

まずサーバーが稼働しているか確認します。 同じように失敗する問題が2つあります。同期状態の破損と、サーバーが起動していないことです。デスクトップアプリの場合、ポート 5007 のサーバーはアプリの起動中だけ稼働するため、アプリが閉じている状態を意味します。repair_sync で修正できるのは前者だけです。そのため、何も待ち受けていない場合はその旨を伝え、アプリが起動していないという問題の修復に処理を費やすことなく、何も変更しません。

パラメーター

repair_sync - パラメーターなし

### 環境

ACTUAL_HTTP_TIMEOUT_MS（任意、デフォルトは 60000）— Actual サーバーが応答を開始するまでの待ち時間です。応答自体は完了まで待つため、予算のダウンロードが遅くても中断されません。この設定がない場合、接続を受け付けても応答しないサーバーによって、すべての書き込みが Node 独自の制限である 5 分間ブロックされます。

1000 未満、タイマーで設定できる上限を超える値、または Infinity を指定した場合は、最も近い上限値に置き換えられ、理由とともに stderr に出力されます。数値でない値、またはゼロや負の値を指定した場合は、何も出力せずデフォルト値が使われます。設定していない人に知らせても意味がないためです。

SDK の仕様から確認できる、この設定の適用範囲は次のとおりです。

• SimpleFIN、Pluggy、Akahu、Enable Banking は、トランザクションを取得する呼び出しに独自の制限時間を設定しているため、この設定ではそれらの時間を短縮できません。SimpleFIN で複数のアカウントを一度に同期する場合を除き、制限時間は 60 秒です。この場合は 300 秒で、デフォルトの銀行同期で使われます。これらの制限時間は応答の開始だけでなく、応答全体に適用されるため、この設定より長くなっています。
• GoCardless は制限時間を設定していないため、トランザクションのダウンロードにはこの設定が適用されます。銀行の応答が遅く、同期が中断される場合は値を大きくしてください。
• これ以外のサーバー処理すべてに適用されます。つまり、お使いの Actual サーバーに対する通常の読み取りと書き込みすべてです。

.mcpb 拡張機能をインストールした場合、同じ設定が構成画面の サーバー応答タイムアウト（ms） にあります。

意図的に対象外としているケースが 1 つあります。サーバーがヘッダーを送信した後、本文の送信を停止するケースです。この時点で期限はすでに満たされているため、そのリクエストを終了させるのは Node 独自の 5 分間の本文タイムアウトです。このケースにも対応するには転送自体に期限を設ける必要がありますが、それをすると、修正前に正常なダウンロードまで中断されていました。

プロンプト

複数ステップの財務分析を Claude に案内する、組み込みのプロンプトテンプレートです。

プロンプト	説明
monthly-review	任意の月の予算を総合的に確認します。支出と予算の比較、予算超過、提案を含みます
spending-check	今月の予算どおりに進んでいるかを手早く確認します
spending-patterns	複数月にわたる支出の傾向やパターンを詳しく分析します

Claude Desktop ではプロンプトアイコンをクリックして、Claude Code では Claude に使用するよう依頼して利用できます。

リソース

ツールを呼び出さずに Claude が参照できる、事前に読み込まれたデータです。

リソース	URI	説明
アカウント	actual://accounts	残高を含むすべてのアカウント
カテゴリー	actual://categories	ID 付きのカテゴリーグループとカテゴリー
受取人	actual://payees	アルファベット順に並んだすべての受取人

使用例

実際に使えるプロンプトを紹介します。

"How much did I spend in February?"

"Show me my top 5 spending categories this month"

"Am I over budget on anything?"

"I spent 1,200 on electricity from my checking account yesterday"

"What's my savings rate this month?"

"Show me all transactions from Wallet in the last 30 days"

"Transfer 5,000 from Checking to Savings"

"What are my spending trends for food over the last 6 months?"

"Create a category called Gym in Variable Spending"

"Rename the Gym category to Fitness"

"Create a rule: when payee is Netflix, set category to Suscripciones"

"How have my finances been the last 3 months?"

他との違いは？

他の Actual Budget MCP サーバーと比較すると、次のような違いがあります。

機能	actual-budget-mcp	その他
自然言語での日付指定	「先月」、「今月」、「3 か月前」	YYYY-MM-DD のみ
名前の解決	UUID の代わりに「Wallet」と入力	正確な ID が必要
出力形式	整列された表、読みやすいテキスト	生の JSON
エラーメッセージ	修正方法を明確に説明	一般的なエラー
分析ツール	予算と実績、予測、傾向	利用不可
MCP プロンプト	3 つの分析ワークフローを案内	限定的、またはなし
MCP リソース	アカウント、カテゴリー、受取人を事前に読み込み	利用不可
日付の多言語対応	英語 + スペイン語	英語のみ
振替	対応する 2 つの側、照合可能な transfer_id、カテゴリーなし。アプリと同じ動作	多くの場合、片側のみ、または誤ったカテゴリーに分類
削除	プレビュー後、明示的に確認	即時実行
同期ずれからの復旧	repair_sync でローカルの同期状態を再構築	再インストールして復旧を期待
API バージョン	@actual-app/api 26.x（現行）	古いバージョンが多い

セキュリティ

• このサーバーは、提供された認証情報を使用して Actual Budget インスタンスに接続します
• 認証情報は環境変数として渡され、MCP サーバーに保存されることはありません
• Actual Budget サーバーとのすべての通信はローカルで行われます（またはセルフホストしたサーバーに対して行われます）
• サーバーは、公式の @actual-app/api ライブラリを通じてのみ予算データにアクセスします
• 第三者にデータが送信されることはありません

トラブルシューティング

ここに記載されていないことでお困りですか？つまずいた点をお知らせください。一言で十分です。こちらから見ると、セットアップに失敗した場合と、セットアップがまったく行われていない場合に違いはありません。

「Actual Budget サーバーに接続できませんでした」

• Actual Budget が実行中であることを確認してください（アプリを開くか、サーバーを起動してください）
• ACTUAL_SERVER_URL が正しいことを確認してください
• npx -y actual-budget-mcp --verify を実行して接続をテストしてください

「認証に失敗しました」

• サーバーでパスワードが必要です。設定に ACTUAL_PASSWORD を設定してください
• パスワードを忘れた場合は、Actual Budget の［設定］>［サーバー］からリセットしてください

「予算が見つかりません」

• ACTUAL_BUDGET_ID を確認してください。［設定］>［詳細設定を表示］>［同期 ID］で確認できます

「予算ファイルが暗号化されています」

• 暗号化パスワードを ACTUAL_ENCRYPTION_PASSWORD に設定してください

「曖昧な名前です：X、Y に一致します」

• もっと具体的に指定してください。「Main」の代わりに「Main Checking」や「Main Savings」を試してください

Node.js の要件

サーバーがすぐに終了する、またはメッセージなしでクラッシュする

• 0.10.1 以降では、最低要件は Node 22.14 です。Actual の SQLite ライブラリは N-API 10 を使ってビルドされており、これはこのリリースで導入されます。古い Node では、バイナリの読み込み後、予算を開く際に セグメンテーション違反が発生します。22.13.1 での測定結果は、終了コード 139、メッセージなし、スタックトレースなし、どのログにも記録なしでした。サーバーを再起動するホストでは、この状態が延々と繰り返されます。
• サーバーは現在、起動時にこの問題を確認し、クラッシュする代わりにその旨を表示します。ただし、これは 0.10.1 以降のみです。
• 解決策： Node 22.14 以降を実行するか、Node を同梱する Docker イメージを使用してください。

「ReferenceError: navigator is not defined」

• @actual-app/api は 26.6 まで navigator グローバルを参照していました。このグローバルは Node.js 21 以降にしか存在しないため、Node.js 20 でライブラリをインポートすると、サーバーの起動前にエラーが発生していました。26.8 ではこの参照が削除されました。
• 解決策： Node.js 22.14 以降を実行してください。

このサーバーを使用した後、Actual アプリで予算を開けなくなる

• 予算を開くと、ファイルには含まれずライブラリに含まれるマイグレーションが実行され、次回の同期でその結果がアップロードされます。0.10.1 以降、このサーバーには Actual 26.10 が含まれているため、26.9 のサーバーに接続すると予算が新しい形式にマイグレーションされ、26.9 のままの Actual アプリでは開けなくなります。測定結果では、マイグレーション数が 59 から 60 に増えます。
• Actual の公式アプリも更新時にはまったく同じ処理を行います。異なるのは、ほかのものを更新する前に、このサーバーが予算にアクセスする可能性があることです。
• サーバーは、Actual サーバーがライブラリより古いと検出した場合、何かをダウンロードする前に起動時の警告を表示します。
• 解決策： このバージョンを使用する前に、Actual サーバーとアプリを 26.10 以降に更新してください。すでにこの問題が発生している場合は、更新すると予算を再び開けるようになり、データも失われません。

「version `GLIBC_2.34' not found」、または古い Linux で予算が開かない

• Linux 用の Actual の SQLite バイナリは glibc 2.34 に対してビルドされているため、glibc が古い Debian 11、Ubuntu 20.04、RHEL 8 では読み込めません。Debian 11 の libc での測定結果は、version 'GLIBC_2.33' not found でした。
• これを回避する方法はありません。package.json の override は npx でのインストールには適用されず、バイナリはライブラリに含まれているものだからです。
• 解決策： 独自の glibc を同梱する Docker イメージ、または glibc 2.34 以降を搭載したディストリビューション（Debian 12、Ubuntu 22.04、RHEL 9）を使用してください。

ソースからのインストール時に「gyp ERR! find Python」が発生する

• クローンからインストールすると npm ci が実行されます。npm は binding.gyp を含むパッケージをビルドしますが、better-sqlite3 はビルド不要であるにもかかわらず、これに該当します。使用するバイナリはすでにパッケージに含まれているためです。
• 解決策： npm ci --ignore-scripts を実行してください。失われるものはありません。拡張機能と Docker イメージでも同じ方法を使用しています。

Node バージョンマネージャー（fnm、nvm、volta）

Claude Desktop で MCP サーバーに「Server disconnected」と表示される

• Claude Desktop はシェルのプロファイル（.bashrc、.zshrc）を読み込まないため、fnm、nvm、volta などのバージョンマネージャーはデフォルトの npx コマンドでは動作しません。これは設定ファイルに手動で npx を指定した場合に該当し、依存関係を独自に含む Desktop Extension には該当しません。
• 解決策： 設定で node の絶対パスを使用してください。次のコマンドで確認できます。

readlink -f $(which node)

次に、claude_desktop_config.json を更新してください。

{
  "mcpServers": {
    "actual-budget-mcp": {
      "command": "/home/user/.local/share/fnm/node-versions/v22.22.1/installation/bin/node",
      "args": ["/path/to/actual-budget-mcp/dist/index.js"],
      "env": {
        "ACTUAL_SERVER_URL": "http://localhost:5006",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_BUDGET_ID": "your-budget-sync-id"
      }
    }
  }
}

または、ラッパースクリプト mcp-wrapper.sh を作成します。

#!/bin/bash
export PATH="$HOME/.local/share/fnm/node-versions/v22.22.1/installation/bin:$PATH"
exec npx -y actual-budget-mcp "$@"

その後、設定で使用します。

{
  "mcpServers": {
    "actual-budget-mcp": {
      "command": "/path/to/mcp-wrapper.sh"
    }
  }
}

コントリビューション

コントリビューションを歓迎します。issue を作成するか、プルリクエストを送信してください。

git clone https://github.com/henfrydls/actual-budget-mcp.git
cd actual-budget-mcp
npm install
npm run build
npm test               # Run unit tests
npm run test:connection # Needs .env configured

ライセンス

MIT - DLSLabs