Actual Budget MCP Server

Actual Budget MCP Server

Actual Budget を Claude やその他の LLM アシスタントと連携するための MCP サーバーです。

概要

Actual Budget MCP Server を使用すると、LLM を通じて自然言語で Actual Budget の個人財務データを操作できます。Model Context Protocol（MCP）を介して、口座、取引、財務指標を公開します。

機能

リソース

• 口座一覧 - 残高を含むすべての口座を確認します
• 口座の詳細 - 特定の口座に関する詳細情報を表示します
• 取引履歴 - 詳細情報を含む取引データにアクセスします

ツール

取引と口座の管理

• get-transactions - 口座、日付、金額、カテゴリ、または支払先で取引を取得・絞り込みます
• create-transaction - 任意でカテゴリ、支払先、メモを指定して、口座に新しい取引を作成します
• update-transaction - 既存の取引のカテゴリ、支払先、メモ、または金額を更新します
• get-accounts - 現在の残高と ID を含む、すべての口座の一覧を取得します
• balance-history - 口座残高の経時変化を確認します

レポートと分析

• spending-by-category - 種類別の支出内訳を生成します
• monthly-summary - 月ごとの収入、支出、貯蓄指標を取得します
• budget-vs-actual - カテゴリごとに予算額と実際の支出額を比較します
• net-worth - すべての口座にわたる資産、負債、純資産の推移を追跡します
• category-trends - カテゴリごとの支出の月次推移と傾向を確認します
• spending-by-payee - 支払先ごとの支出額（または受取額）をランキング表示します
• cash-flow - 月ごと、または週ごとの収入、支出、純キャッシュフローをレポートします

上記の 5 つのツールは Markdown ではなく JSON を返すため、金額を機械可読な形式で保持できます。金額はすべてセント単位の整数で、各レスポンスには使用されている符号規則を示す amountsIn フィールドが含まれます。

カスタムレポートとダッシュボード

• get-custom-reports - レポートセクションに保存されているすべてのカスタムレポートを取得します
• create-custom-report - 保存済みのカスタムレポートを作成します
• update-custom-report - 保存済みのカスタムレポートのフィールドを更新し、その他の項目は変更しません
• delete-custom-report - 保存済みのカスタムレポートを削除します
• get-dashboards - すべてのダッシュボードページと、そこに配置されたウィジェットを取得します
• add-dashboard-widget - ダッシュボードページにウィジェットを追加します
• update-dashboard-widget - ウィジェットの設定、位置、またはサイズを更新します
• remove-dashboard-widget - ページからウィジェットを削除します
• organize-dashboard - 複数のウィジェットの位置とサイズをまとめて変更します
• create-dashboard-page / rename-dashboard-page / delete-dashboard-page - ダッシュボードページを管理します

カテゴリ

• get-grouped-categories - すべてのカテゴリグループとそのカテゴリの一覧を取得します
• create-category - カテゴリグループ内に新しいカテゴリを作成します
• update-category - 既存のカテゴリの名前またはグループを更新します
• delete-category - カテゴリを削除します
• create-category-group - 新しいカテゴリグループを作成します
• update-category-group - カテゴリグループの名前を更新します
• delete-category-group - カテゴリグループを削除します

支払先

• get-payees - 詳細情報を含むすべての支払先の一覧を取得します
• create-payee - 新しい支払先を作成します
• update-payee - 既存の支払先の詳細を更新します
• delete-payee - 支払先を削除します
• merge-payees - 重複する支払先を 1 つの統合先にまとめます

ルール

• get-rules - すべての取引ルールの一覧を取得します
• create-rule - 条件とアクションを指定して新しい取引ルールを作成します
• update-rule - 既存の取引ルールを更新します
• delete-rule - 取引ルールを削除します

プロンプト

• financial-insights - 財務データに基づいて分析結果と推奨事項を生成します
• budget-review - 予算の遵守状況を分析し、調整を提案します

インストール

前提条件

• Node.js（v16 以降）
• Actual Budgetがインストールされ、設定済みであること
• Claude Desktopまたはその他の MCP 対応クライアント
• Docker Desktop（任意）

リモートアクセス

最新の Docker イメージを取得します。

docker pull sstefanov/actual-mcp:latest

ローカルセットアップ

1. リポジトリをクローンします。

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

2. 依存関係をインストールします。

npm install

3. サーバーをビルドします。

npm run build

4. ローカルの Docker イメージをビルドします（任意）。

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

5. 環境変数を設定します（任意）。

# 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"

任意：予算用の暗号化パスワードを分ける

Actual のセットアップで、ローカル／暗号化された予算データのロック解除にサーバー認証パスワードとは別のパスワードが必要な場合は、ACTUAL_PASSWORDに加えてACTUAL_BUDGET_ENCRYPTION_PASSWORDを設定できます。

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

任意：OpenID サーバー（セッショントークン認証）

Actual サーバーが OpenID ログイン（Google など）を使用し、ACTUAL_OPENID_ENFORCE=trueが設定されている場合、パスワードログインは無効になるため、ACTUAL_PASSWORDは使用できません。代わりに、ブラウザーで Actual にサインインし、取得したセッショントークンを渡してください。このトークンはACTUAL_PASSWORDより優先されます。

export ACTUAL_SERVER_URL="https://your-actual-server.com"
export ACTUAL_SESSION_TOKEN="your-session-token"

トークンを確認するには、ブラウザーで Actual にサインインし、DevTools を開いてApplication → IndexedDB → actual → asyncStorageに移動します。user-tokenキーの値がセッショントークンです。これは UUID（例：3f2b8c1e-9a4d-4e7b-8c2a-1d5e6f7a8b9c）であり、長い JWT 形式のベアラートークンではありません。curl -H "X-ACTUAL-TOKEN: <token>" https://your-actual-server.com/account/validateを実行して確認できます。"validated": trueが返されるはずです。このトークンはパスワードと同様に扱ってください。予算への完全なアクセス権を与えます。有効期間はサーバーのACTUAL_TOKEN_EXPIRATION設定によって異なります。無効または期限切れの場合でも MCP サーバーは起動しますが、サーバーは最初のリクエスト時に Actual に接続するため、ツールの呼び出しはAuthentication failed: invalid or expired session tokenで失敗します（--test-resourcesを実行すると、エラーがすぐに報告されます）。再度サインインし、トークンを置き換えてから、MCP サーバーを再起動してください。

接続のライフサイクル

サーバーは稼働中、共有の Actual 接続を1つ維持し、その接続を通じて予算関連の操作を順番に処理します。ダウンロード済みデータがACTUAL_SYNC_TTL_MSの鮮度期間を超えると、再同期されます。stdio モードと HTTP モードのどちらでも、サーバーの終了時には SIGINT と SIGTERM によって処理中の作業が完了してからシャットダウンします。各ツール呼び出しのたびに Actual を初期化・終了することはなくなりました。

レポートの仕様

• 残高と残高履歴は今日時点での値に制限されます。未来日付の取引は除外され、当月の残高履歴は一部のみです。
• 予算対象の閉鎖済み口座は過去のレポートに引き続き含まれます。予算対象外の閉鎖済み口座は、デフォルトでは除外されます。
• 月ごとの収入は Actual の収入グループのメタデータに従います。返金は支出と相殺され、活動のない月も平均に含まれ、カテゴリ未設定の振替ペアはスキップされます。
• 月次サマリーから従来の「投資」項目は削除されています。

Claude Desktop での使用方法

このサーバーを Claude Desktop で使用するには、Claude の設定に追加してください。

MacOS の場合：

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows の場合：

code %APPDATA%\Claude\claude_desktop_config.json

設定に次の内容を追加します……

a. Node.js を使用する場合（npx 版）：

{
  "mcpServers": {
    "actualBudget": {
      "command": "npx",
      "args": ["-y", "actual-mcp", "--enable-write"],
      "env": {
        "ACTUAL_DATA_DIR": "path/to/your/data",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_SERVER_URL": "http://your-actual-server.com",
        "ACTUAL_BUDGET_SYNC_ID": "your-budget-id"
      }
    }
  }
}

### a. Using Node.js (local only):

```json
{
  "mcpServers": {
    "actualBudget": {
      "command": "node",
      "args": ["/path/to/your/clone/build/index.js", "--enable-write"],
      "env": {
        "ACTUAL_DATA_DIR": "path/to/your/data",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_SERVER_URL": "http://your-actual-server.com",
        "ACTUAL_BUDGET_SYNC_ID": "your-budget-id"
      }
    }
  }
}

b. Docker を使用する場合（ローカルまたはリモートのイメージ）：

{
  "mcpServers": {
    "actualBudget": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/data:/data",
        "-e",
        "ACTUAL_PASSWORD=your-password",
        "-e",
        "ACTUAL_SERVER_URL=https://your-actual-server.com",
        "-e",
        "ACTUAL_BUDGET_SYNC_ID=your-budget-id",
        "sstefanov/actual-mcp:latest",
        "--enable-write"
      ]
    }
  }
}

設定を保存した後、Claude Desktop を再起動してください。

💡 ACTUAL_SERVER_URLを使用している場合、ACTUAL_DATA_DIRは省略できます。

💡 書き込みアクセス用のツールを有効にするには、--enable-writeを使用してください。

SSE サーバーの実行

Docker を使用してサーバーをポート経由で公開するには：

docker run -i --rm \
  -p 3000:3000 \
  -v "/path/to/your/data:/data" \
  -e ACTUAL_PASSWORD="your-password" \
  -e ACTUAL_SERVER_URL="http://your-actual-server.com" \
  -e ACTUAL_BUDGET_SYNC_ID="your-budget-id" \
  -e BEARER_TOKEN="your-bearer-token" \
  sstefanov/actual-mcp:latest \
  --sse --enable-write --enable-bearer

⚠️ 重要：--enable-bearer を使用する場合、BEARER_TOKEN 環境変数を設定する必要があります。
🔒 パブリック URL 経由でサーバーを公開する場合は、これを強く推奨します。

質問例

接続すると、Claude に次のような質問ができます。

• 「現在の口座残高はいくらですか？」
• 「先月のカテゴリ別の支出を表示してください」
• 「1月に食料品にいくら使いましたか？」
• 「過去3か月間の貯蓄率はいくらですか？」
• 「今月、どのカテゴリで使いすぎていますか？」
• 「過去1年間で純資産はどのように変化しましたか？」
• 「最も多く支出している支払先はどこですか？」
• 「食料品の支出は増加傾向ですか、減少傾向ですか？」
• 「予算を分析して、改善できる項目を提案してください」
• 「どのようなカスタムレポートがありますか？」
• 「Spending Plan ダッシュボードに純資産ウィジェットを追加してください」
• 「キャッシュフローカードが上部で全幅になるように、ダッシュボードを並べ替えてください」

Codex CLI での使用方法

Codex の設定例：

~/.codex/config.toml 内：

[mcp_servers.actual-budget]
url = "http://localhost:3000"

npm start -- --sse --port <PORT> に渡すポートと同じポートを Codex に指定してください。

開発

自動再ビルドを使った開発の場合：

npm run watch

Actual への接続テスト

サーバーが Actual Budget のデータに接続できることを確認するには：

node build/index.js --test-resources

デバッグ

MCP サーバーは stdio 経由で通信するため、デバッグが難しい場合があります。MCP Inspector を使用できます。

npx @modelcontextprotocol/inspector node build/index.js

E2E 検証ゲート

エンドツーエンドテストスイート（vitest.e2e.config.ts）は、Docker コンテナ内で実際の Actual Budget サーバーを起動し（Testcontainers 経由）、予算データを登録したうえで、stdio 経由の実際の MCP クライアントを使って操作し、口座、取引、カテゴリ、支払先、ルール、インポートが実際に永続化されることを検証します。ローカルで Docker が実行されている必要があります。

CI では、.github/workflows/pr-validation.yml の e2e-test ジョブは、release-please の PR（ブランチプレフィックス release-please--）の場合、または PR に run-e2e ラベルが付いている場合にのみ実行されます。Docker が必要で、標準チェックより時間がかかるため、デフォルトではすべての PR で実行されるわけではありません。

ローカルで実行するには：

npm run build && npm run test:e2e

Docker をインストールして実行しておく必要があります。テストスイートは Actual サーバーのイメージを自動的に取得して起動します。

プロジェクト構成

• index.ts - メインのサーバー実装
• types.ts - API レスポンスとパラメーターの型定義
• prompts.ts - LLM とのやり取りに使用するプロンプトテンプレート
• utils.ts - 日付の書式設定などを行うヘルパー関数

レジストリとディスカバリー

actual-mcp は公式 MCP Registry に io.github.s-stefanov/actual-mcp として公開されています。レジストリのメタデータは server.json にあり、リリースごとに自動で公開されます （.github/workflows/release-please.yml を参照）。

npm パッケージでは、stdio（デフォルト）と streamable-http（--sse フラグ経由）の2つのトランスポートを提供しています。（Docker イメージも公開されていますが、 まだレジストリのパッケージとして登録されていません。）

リリース後のディレクトリ掲載状況は docs/mcp-registry-checklist.md で管理されています。

ライセンス

MIT

コントリビューション

コントリビューションを歓迎します。お気軽にプルリクエストを送信してください。