ZenMoney

mcp-server-zenmoney

ZenMoney（Дзен-мани）用の MCP サーバーです。AI エージェントが口座や残高にアクセスし、取引を検索してレポートを作成したり、月次予算を読み取って設定したり、予定（定期）取引や負債を確認したり、支出を分類したり、安全対策を施したうえで取引を記録・編集したりできます。OAuth トークン（たとえば、Zerro で発行されたもの）を使用して、公式の ZenMoney API v8（POST /v8/diff/ 同期プロトコルと POST /v8/suggest/）と通信します。

非公式プロジェクトであり、ZenMoney または Zerro とは提携していません。トークンとデータはお使いのマシン内に保持されます。

クイックスタート

必要条件：Node.js >= 22。

1. トークンを取得します：https://zerro.app/token を開き、ZenMoney アカウントでログインして、表示されたトークンをコピーします。
2. トークンを検証します：ZENMONEY_TOKEN=... npx -y mcp-server-zenmoney --check を実行すると、OK: <login>, main currency …, N active accounts, M transactions が出力されます（それ以外の場合は、理由とともに終了コード 1 が返されます）。
3. エージェントにサーバーを追加します（以下を参照）。

トークンがなくてもサーバーは起動します。その場合、各ツールがトークンの設定方法を説明します。

エージェントに接続する（stdio）

Claude Code

claude mcp add zenmoney -e ZENMONEY_TOKEN=YOUR_TOKEN -- npx -y mcp-server-zenmoney

Claude Desktop / Cursor / ほとんどの MCP クライアント

claude_desktop_config.json、~/.cursor/mcp.json、…：

{
  "mcpServers": {
    "zenmoney": {
      "command": "npx",
      "args": ["-y", "mcp-server-zenmoney"],
      "env": { "ZENMONEY_TOKEN": "YOUR_TOKEN" }
    }
  }
}

omp

ユーザー全体の設定 ~/.omp/agent/mcp.json（またはプロジェクトごとの .omp/mcp.json）の mcpServers 内に記述します：

"zenmoney": {
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "mcp-server-zenmoney"],
  "env": { "ZENMONEY_TOKEN": "${ZENMONEY_TOKEN}" }
}

omp は ${VAR} プレースホルダーを展開するため、トークンはシェル環境に保持できます。その後、/mcp reload を実行します。

トークンを設定ファイルに記載しない

umask 077 && printf '%s' 'YOUR_TOKEN' > ~/.config/zenmoney-token

ZENMONEY_TOKEN の代わりに "env": { "ZENMONEY_TOKEN_FILE": "~/.config/zenmoney-token" } を使用します。

読み取り専用

"ZENMONEY_READ_ONLY": "true" を env に追加するか、args に --read-only を追加します。書き込みツールは登録されなくなります。

HTTP モード

ZENMONEY_TOKEN=... npx -y mcp-server-zenmoney --http --port 3000

• MCP エンドポイント（Streamable HTTP）：http://127.0.0.1:3000/mcp。GET /health は {"ok":true} を返し、その他のパスはすべて 404 になります。
• デフォルトのバインド先は 127.0.0.1 です。ループバックへのバインド（127.0.0.1、localhost、::1）では、DNS リバインディング対策として Host/Origin の検証が行われます。
• MCP_HTTP_TOKEN が設定されていない場合、その他の --host / MCP_HTTP_HOST は拒否されます。設定されている場合（バインド先を問わず）、クライアントは Authorization: Bearer <MCP_HTTP_TOKEN> を送信する必要があります。送信しない場合は 401 が返されます。これは単一ユーザー向けのサーバーです。そのトークンを持つ人は誰でも ZenMoney にアクセスできるため、プライベートネットワーク内で保管してください。

設定

変数 / フラグ	デフォルト	説明
ZENMONEY_TOKEN	—	https://zerro.app/token で取得した ZenMoney API トークン
ZENMONEY_TOKEN_FILE	—	トークンを含むファイル（ZENMONEY_TOKEN が空の場合に使用。~ は展開されます）
ZENMONEY_READ_ONLY / --read-only	false	1/true/yes/on の場合、読み取りツールのみを登録します
ZENMONEY_SYNC_TTL	30	次のツール呼び出し時にデータを再同期するまでの秒数
ZENMONEY_CACHE_DIR	$XDG_CACHE_HOME/mcp-server-zenmoney、それ以外は ~/.cache/mcp-server-zenmoney	スナップショットのキャッシュディレクトリ
ZENMONEY_CACHE	on	0/false/no/off の場合、データはメモリ内にのみ保持されます
ZENMONEY_API_URL	https://api.zenmoney.ru、フォールバック先は https://api.zenmoney.app	使用する API オリジンを 1 つに固定します
MCP_TRANSPORT / --http	stdio	http の場合、Streamable HTTP を提供します
MCP_HTTP_HOST / --host	127.0.0.1	HTTP のバインドアドレス
MCP_HTTP_PORT / --port	3000	HTTP ポート
MCP_HTTP_TOKEN	—	HTTP クライアントが送信する必要のあるベアラートークン。ループバック以外へのバインドでは必須です
--check	—	設定済みのトークンで一度同期し、1 行の概要を出力して終了します
--help、-h / --version、-v	—	使用方法 / バージョンを出力します

CLI フラグは、対応する環境変数より優先されます。

ツール

読み取りツール（常に登録され、readOnlyHint が付与されています）：

ツール	目的
get_overview	ここから始めてください：今日の日付、メイン通貨、純資産、口座残高、今月の収入／支出、今後予定されている取引、データの鮮度
list_accounts	残高（メイン通貨での金額も）、与信限度額、銀行、フラグを含む口座一覧
list_categories	種類（支出／収入／両方）と過去12か月の使用回数を含むカテゴリーツリー
list_payees	使用頻度順に並べた既知の支払先と、最終日付および通常のカテゴリー
list_transactions	絞り込み・ページ分割に対応した取引検索と、一致するすべての取引の収入／支出合計
summarize_transactions	カテゴリー、親カテゴリー、支払先、口座、または日／週／月／年ごとの集計。キャッシュフローには measure=both を指定
get_budget	カテゴリーごとの月間予算と実績、残額、使用率、まだ予定されている取引
list_planned	日付範囲内で未処理の予定／定期取引と、見込み合計
list_debts	人ごとの債務残高（正の値は相手があなたに借りていることを示します）。任意で、その人の債務取引も取得できます
suggest_category	ZenMoney とあなた自身の履歴に基づく、支払先名に対するカテゴリー／加盟店の候補
sync	ZenMoney から変更を今すぐ取得します。full=true を指定するとすべてを再ダウンロードします

書き込みツール（読み取り専用モードでは登録されません）：

ツール	目的
create_transactions	最大50件の支出、収入、振替、債務取引を記録します。カテゴリーを自動で割り当て、重複を警告します
update_transactions	金額、口座、カテゴリー、支払先、コメント、日付、元の金額を編集します。振替先も変更できます。取引の種類は変更できません
delete_transactions	ID を指定して取引を論理削除します
restore_transactions	削除した取引を新しい ID のコピーとして復元します
create_category	カテゴリーまたはサブカテゴリーを作成します（階層は1段階）
update_category	名前、移動先、種類、予算への算入、必須フラグ、アーカイブ状態を変更します
delete_category	カテゴリーを削除し、その取引と予定取引を move_to に移動するか、カテゴリー未設定にします
set_budgets	カテゴリーごとに月間予算を指定します。total または uncategorized を指定でき、0 で削除します
create_account	現金、カード、当座預金、電子マネーの口座を作成します
update_account	名前、アーカイブ状態、残高への算入／除外、貯蓄フラグ、与信限度額を変更します
adjust_account_balance	修正収入／支出を記録して、実際の残高に合わせます

書き込みツールには MCP アノテーションが付与されます。作成ツールは非破壊的（destructiveHint: false）で、編集／削除ツールは破壊的（destructiveHint: true）です。そのため、ヒントに対応するクライアントでは確認を求めることができます。

create_transactions、update_transactions、delete_transactions、delete_category、set_budgets は dry_run: true を受け付けます。すべてを解決し、ZenMoney に送信せずに実行予定の結果を返します（更新の場合は取引ごとの before／after）。

プロンプト

MCP プロンプト（スラッシュコマンドなど）に対応するクライアントでは、上記のツールを調整する次の3つのワークフローを利用できます。

プロンプト	引数	内容
monthly_review	month（YYYY-MM）	収入、前月比の支出、予算状況、高額取引、今後の支払い、提案
categorize_transactions	period	カテゴリー未設定の取引に対するカテゴリーを提案し、確認後に適用します（最初にドライランを実行）
plan_budget	month（YYYY-MM）	過去3か月分と予定支払いをもとに予算を提案し、確認後に set_budgets で適用します

規約

以下はサーバー指示としてエージェントにも送信されます。

• 金額は常に正の値です。方向は type で指定します：expense（支出）、income（収入）、transfer（自分の口座間の振替）、debt_out（貸付または返済として人に渡したお金）、debt_in（借入または返済として受け取ったお金）。
• 口座とカテゴリは、名前（大文字・小文字と絵文字を区別せず、一意に特定できる部分文字列でも可）、"Parent / Child" 形式のカテゴリパス、または ID で指定します。口座はカード番号の末尾の数字（4 桁以上）でも指定できます。
• 通貨は ISO コード（RUB、USD、KZT など）です。日付は YYYY-MM-DD 形式です。
• クエリツールでは period として、today、yesterday、this_week、last_week、this_month、last_month、this_quarter、last_quarter、this_year、last_year、last_7_days、last_30_days、last_90_days、last_12_months を指定できます（週の開始日は月曜日です。date_from／date_to を指定すると、いずれかの端の日付が上書きされます）。
• レポートは ZenMoney の現在の為替レートでメイン通貨に換算され、ZenMoney と同様に、特に指定がない限り残高に含まれる口座のみを集計します。集計から振替と債務は除外されます。list_transactions が返す合計値も同じルール（残高に含まれる口座、未削除）に従います。表示される取引に残高に含まれない口座の取引や削除済みの取引が含まれていても同様です。
• 新しい取引で支出／収入カテゴリが指定されていない場合、まずこの支払先の履歴からカテゴリが補完され、次に ZenMoney の提案サービスが利用されます（適切な種類の有効なカテゴリのみ）。既存の取引と一致する新しい取引（同じ日付、種類、口座、金額）には重複警告が表示されますが、記録はされます。
• update_transactions の category はメインカテゴリを置き換え、副次タグは維持します。null を指定すると、取引はカテゴリなしになります。別の通貨の口座に取引を移すには、新しい amount が必要です。同じ通貨の振替で amount だけを変更すると、受取額に差があった場合（手数料）はその差を維持したうえで、両側の金額が更新されます。
• 書き込みのたびに、まず ZenMoney と同期してから、一度に 1 件ずつ処理します。そのため、直前にアプリで行った編集が上書きされず、並行するツール呼び出しによって互いの変更が上書きされることもありません。アプリで削除されたカテゴリ／加盟店への参照は、バッチ全体を失敗させず、プッシュするオブジェクトから除外されます。
• ZenMoney が書き込みを受け付けても応答が失われた場合（タイムアウト）、変更が保存されたかどうかは不明であるとツールが通知します。次の呼び出しで再同期されるため、再試行すると、二重に記録されることなく重複警告が表示されます。
• 削除は論理削除です。ZenMoney では削除した取引をその場で復元できないため、restore_transactions は各取引を新しい ID で再作成します。同じ取引を再度復元しても何も起こらず、既存のコピーが示されます。
• 予算：set_budgets は金額を指定値に設定します（ロックが有効になります）。0 を指定すると予算が削除されます。ロックなしの予算（アプリで設定したもの）には、ZenMoney と同様に、その月の予定取引も含まれます。プロフィールで設定した月の開始日が適用されます。月をまたぐ繰り越しはモデル化されません。
• Zerro の非表示の 🤖 [Zerro Data] 口座と、それに紐づくリマインダーは、すべての処理で無視されます。

プロンプトの例

• 「10 月はどうだった？主なカテゴリと、9 月と比べて何か変わった点はある？」
• 「追加して：今日、Kaspi Gold から Magnum で 12 450 KZT、食料品。」
• 「先月の Yandex Go の乗車をすべて、Transport / Taxi に再分類して。」
• 「今月の予算を来月にコピーして、Restaurants だけ 80 000 に増やして。」
• 「私にお金を返す必要がある人は誰？合計はいくら？」
• 「今後 2 週間に予定されている支払いは？」
• 「現金の財布には実際には 23 000 ある。残高を修正して。」

データ、プライバシー、同期

• サーバーは、/v8/diff/ を介して同期される ZenMoney データベースのローカルレプリカを保持します。初回使用時は全データをダウンロードし、その後は差分を取得します。ZENMONEY_SYNC_TTL 秒より古いデータは、ツールの実行前に自動更新されます。sync を指定すると、強制的に同期されます。
• レプリカは <cache dir>/snapshot-<hash>.json に保存されます（ディレクトリは 0700、ファイルは 0600 の権限で作成されます）。ファイル名はトークンと API オリジンのハッシュであり、トークン自体がディスクに書き込まれることはありません。スナップショットには金融データが含まれます。すべてをメモリ内に保持するには、ZENMONEY_CACHE=off を設定してください。
• API オリジンは、まず https://api.zenmoney.ru を使用します。リクエストが一度も成功する前にトークンが拒否された場合は、https://api.zenmoney.app を試します。ZENMONEY_API_URL を設定すると、単一のオリジンに固定されます。
• ZenMoney からの HTTP 401 は、トークンが無効になったことを意味します。https://zerro.app/token で新しいトークンを取得してください。
• 「今日」とデフォルトの日付には、プロセスのタイムゾーンが使用されます。エージェントのホストが異なるタイムゾーンで動作する場合は、サーバーの env で TZ（例：TZ=Asia/Almaty）を設定してください。
• 使用しなくなったトークンのスナップショットはキャッシュディレクトリに残ります。トークンを更新した後、古い snapshot-*.json ファイルを削除してください。
• ログは stderr のみに出力されます。

制限事項

• 予定（繰り返し）取引は読み取れますが、作成や編集はできません。
• ローン口座と預金口座は作成できません。銀行と同期された口座は ZenMoney 自体によって作成されます。
• 残高を直接編集することはできません。adjust_account_balance は修正取引を記録します。
• レポートの通貨換算には、過去の為替レートではなく現在の為替レートが使用されます。
• Zerro のエンベロープ予算の繰り越しは計算されません。

開発

git clone https://github.com/krax1337/mcp-server-zenmoney && cd mcp-server-zenmoney
npm install         # also builds dist/
npm run typecheck   # tsc --noEmit
npm test            # vitest; offline, against an in-repo fake ZenMoney server in test/
node dist/index.js  # run the local build

リリースするには、package.json と server.json の version を更新し、vX.Y.Z タグをプッシュします。Publish ワークフローではテストを実行し、Trusted Publishing を介して npm（トークン不要、プロベナンス付き）に公開し、MCP Registry に io.github.krax1337/mcp-server-zenmoney として登録します。

ソースの構成：

• src/index.ts — エントリーポイント、stdio および HTTP トランスポート
• src/config.ts — 環境変数と CLI フラグ
• src/server.ts — MCP サーバーとエージェントへの指示
• src/prompts.ts — MCP プロンプト（monthly_review、categorize_transactions、plan_budget）
• src/tools/ — MCP ツール（read.ts、write.ts、共有スキーマとコンテキスト）
• src/zenmoney/ — API クライアント（api.ts）、同期ストアとキャッシュ（store.ts）、台帳のセマンティクス（ledger.ts）、分析機能（analytics.ts）、書き込みビルダー（writes.ts）、日付と型

ライセンス

MIT