monarch-money

Monarch Money MCP サーバー

Monarch Money 用の MCP サーバーです。Monarch Money は、複数の金融機関の口座、取引、予算、純資産を集約する個人向け家計管理アプリです。このサーバーを使うと、AI アシスタントは Monarch のウェブ／モバイルアプリに表示されるのと同じデータに対し、ユーザー自身のアカウントの範囲内で読み取りと書き込みができます。

主な特徴

• 口座、残高、純資産、キャッシュフロー、取引、カテゴリ、タグ、取引ルール、予算を扱う、2 つのグループ（readonly、manage）にまとめられた 23 個のツール
• ~/.monarch-money-mcp/session.enc に暗号化して保存するセッション。サーバーはツール入力を通じて Monarch のパスワードを受け取りません
• 環境変数によるツールグループのフィルタリング。厳密な読み取り専用モードでサーバーを起動するか、エージェントに公開するツールを選んで指定できます
• api.monarch.com/graphql を対象とする独自の軽量 GraphQL トランスポート。サードパーティ製 Monarch クライアントへの依存はありません

独自の GraphQL クライアントを使用する理由

このサーバーのツールは、口座、取引、予算、ルール、カテゴリ、純資産を扱います。既存の TypeScript 製 Monarch クライアントを評価しましたが、必要な範囲を網羅し、かつ積極的にメンテナンスされているものは見つかりませんでした。不完全なサードパーティ製クライアントをラップして不足部分にパッチを当てるのではなく、このサーバーには、意図的に最小限に抑えた独自のトランスポート（shared/src/monarch-client/graphql-transport.ts）が含まれています。リクエストを作成し、型付き例外で認証／ネットワークエラーを通知し、型付けされた data ペイロードを返します。オペレーションは名前付きの GraphQL 文字列として shared/src/monarch-client/operations.ts に記述されているため、grep で検索しやすく、簡単に拡張できます。

認証

Monarch の /auth/login/ エンドポイントでは、使い慣れていないデバイスからの初回ログイン時に、Monarch からメールで送信されるメール OTPの入力が必要です。また、IP ごとのスロットリングと Cloudflare のボットチャレンジもあります。そのため、新規インストールではメールアドレスとパスワードだけで完全に無人のログインフローを実現できません。ユーザーは少なくとも一度、メールからコードを確認する必要があります。この初回のペアリング後は、同じインストール環境で認証情報だけを使ってログインできます。

このため、環境変数に認証情報を設定するよりも、セッショントークンを貼り付ける方法を推奨します。サーバーは、優先順位の高い順に次の 4 つの認証方法をサポートしています。

1. 環境変数のセッショントークン（推奨）

ランチャーの環境変数にトークンを一度貼り付けます。ヘッドレスで自律的に動作し、OTP の確認は不要です。

MONARCH_SESSION_TOKEN=<your-token>

トークンの取得方法：

• npm run login（オプション 3）を一度実行し、~/.monarch-money-mcp/session.enc の内容を（復号後に）コピーする、または
• Monarch のウェブアプリを開き、開発者ツール → ネットワーク → 任意の /graphql リクエストへ進み、Authorization: Token <…> ヘッダーの値をコピーします。

トークンは起動時に取得され、検証された後、ディスクに保存されるため、初回実行後は環境変数が任意になります。

2. ツールを使ったトークンの貼り付け

環境変数を設定できない場合（たとえば、ランチャーの環境変数を公開しない UI を使っている場合）は、トークンを入力として指定し、monarch_login_with_token ツールを呼び出します。サーバーは、Monarch の me エンドポイントを使ってトークンを検証してから保存します。

3. 環境変数のメールアドレス＋パスワード（ベストエフォート）

環境変数に認証情報を設定して、サーバーにログインさせます。

MONARCH_EMAIL=<email>
MONARCH_PASSWORD=<password>
MONARCH_TOTP=<code>          # only if your account has 2FA enabled
MONARCH_EMAIL_OTP=<code>     # only on the first launch from a new install

新規インストールからの初回起動時、Monarch からメールに OTP が送信されます。サーバーは、必要な対応を説明する明確なメッセージを stderr に記録します。MONARCH_EMAIL_OTP=<code> を設定して再起動してください。以降の起動では、保存済みの device-uuid が再利用され、OTP の確認は不要になります。

4. 対話型 CLI

cd servers/monarch-money/local
npm run login

メールアドレス、パスワード、任意の TOTP、チャレンジがあった場合はメール OTP の入力を求めます。暗号化されたトークンを ~/.monarch-money-mcp/session.enc に書き込みます。

セッションの暗号化

トークンは保存時に AES-256-GCM で暗号化されます。暗号化キーは、パスフレーズから scrypt を使って導出されます。

• MONARCH_SESSION_PASSPHRASE が設定されている場合、その値がパスフレーズになります。
• それ以外の場合、マシンのホスト名（os.hostname()）と現在のユーザー（os.userInfo().username）からパスフレーズが導出されます。そのため、デフォルトでは暗号化ファイルはマシンに紐付けられます。

これは、すでにシェルを制御しているローカルの攻撃者への防御にはなりませんが、ホスト間での意図しない情報漏えい（たとえば、ファイルがバックアップに含まれ、別のマシンで復元される場合）は防げます。

ツールグループ

ツールには1つ以上のグループが設定されています。デフォルトではすべてのツールが公開されますが、MONARCH_ENABLED_TOOL_GROUPS（または MONARCH_ENABLED_TOOLS / MONARCH_DISABLED_TOOLS）を設定すると、公開範囲を絞れます。

グループ	含まれる内容
readonly	照会のみ — アカウント、取引、残高、純資産、カテゴリー、予算、ルール。
manage	readonly のすべてに加えて変更操作 — 取引、タグ、ルール、予算の作成／更新／削除、アカウントの更新。

フィルターの優先順位：MONARCH_ENABLED_TOOLS（許可リスト、完全一致の名前）> MONARCH_ENABLED_TOOL_GROUPS（グループフィルター）> MONARCH_DISABLED_TOOLS（拒否リスト、完全一致の名前）。

# Strict read-only deployment
MONARCH_ENABLED_TOOL_GROUPS=readonly

# Deny one specific tool
MONARCH_DISABLED_TOOLS=delete_transaction

# Whitelist exactly two tools
MONARCH_ENABLED_TOOLS=get_transactions,get_accounts

ツール

認証／セッション

ツール	グループ	説明
check_authentication	readonly、manage	ディスク上のセッションが有効か確認します（Monarch の me を呼び出します）。認証されていない場合は、セットアップ手順を返します。
monarch_login_with_token	manage	事前に取得したセッショントークンを、暗号化されたディスクストレージに保存します。

アカウント

ツール	グループ	説明
get_accounts	readonly、manage	残高とメタデータを含む、接続済みのすべてのアカウントを一覧表示します。各アカウントに投資保有資産を含めるには、includeHoldings: true を指定します。
get_account_balance_history	readonly、manage	指定した期間における、1つのアカウントの日次残高スナップショットを返します。
set_account_balance_history	manage	手動アカウントの日次残高スナップショットを設定します。期間モード（開始日／終了日／残高）または明示的な { date, balance } のリストを指定します。Monarch の残高履歴インポーターを使って日付ごとにアップサートします。
refresh_accounts	manage	接続先金融機関との同期を実行します。

純資産

ツール	グループ	説明
get_net_worth	readonly, manage	純資産の表示です。view: "history"（デフォルト）は時系列データを返し、view: "by_type"は口座の種類別に現在の内訳を返します。

取引（読み取り）

ツール	グループ	説明
get_transactions	readonly, manage	viewで5種類の形式の取引を照会します。list（デフォルト。フィルター付きのページ分割表示）、summary（集計合計）、cashflow（収入／支出／貯蓄）、by_category（カテゴリ別の合計）、recurring（予測される発生分）があります。
get_transaction_details	readonly, manage	分割項目を含む、単一の取引の詳細情報です。

取引（書き込み）

ツール	グループ	説明
create_transaction	manage	手動で取引を作成します。
update_transaction	manage	取引を部分更新します。amount／date／merchantId／categoryId／notes／hideFromReports／reviewed／tagIdsを任意の組み合わせで指定できます。bulkTransactionIdsとcategoryIdを渡すと、1回の呼び出しで複数の取引のカテゴリを一括変更できます。
delete_transaction	manage	取引を完全に削除します。
split_transaction	manage	取引を複数のカテゴリ別項目に分割します。

カテゴリとタグ

ツール	グループ	説明
get_categories	readonly, manage	すべてのカテゴリを一覧表示します。includeGroups: true を渡すと、最上位のカテゴリグループも返します。
get_tags	readonly, manage	すべてのタグを一覧表示します。
create_tag	manage	タグを作成します。name と 16 進数の color（例：#19d2a5）が必要です。order はサーバーによって割り当てられます。
delete_tag	manage	id でタグを削除します。{ deleted, errors } を返します。deleted は再読み込みによって確認されます。

取引ルール（自動分類）

ツール	グループ	説明
get_transaction_rules	readonly, manage	設定済みの自動分類ルールを、それぞれのルールの条件とアクションを含めて一覧表示します。
create_transaction_rule	manage	1 つ以上の条件（加盟店／金額／カテゴリ／口座）と、1 つ以上の一致アクションからルールを作成します。
update_transaction_rule	manage	id でルールを更新します。全置換 — ルールのすべての条件とアクションを再指定してください（それぞれ 1 つ以上）。省略したフィールドはルールから消去されます。
delete_transaction_rule	manage	id でルールを完全に削除します。

予算

ツール	グループ	説明
get_budgets	readonly, manage	設定済みの予算を一覧表示します。
set_budget_amount	manage	カテゴリの予算額を設定します。

クイックスタート

インストール

npx monarch-money-mcp-server

認証

# Clone the repo, cd into this server, then:
cd local
npm run login
# Prompts for email, password, TOTP — writes encrypted token to ~/.monarch-money-mcp/session.enc

Claude Desktop の設定

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

{
  "mcpServers": {
    "monarch-money": {
      "command": "npx",
      "args": ["-y", "monarch-money-mcp-server"]
    }
  }
}

Claude Desktop を再起動すれば、準備完了です。サーバーは暗号化されたセッションファイルをディスクから読み込みます。通常の使用では環境変数は必要ありません。

環境変数

変数	必須	説明	デフォルト
MONARCH_SESSION_TOKEN	いいえ	事前に取得したセッショントークンです。起動時に解決され、初回実行時にディスクに保存されます。	(なし)
MONARCH_EMAIL	いいえ	環境変数によるログイン用のメールアドレスです（MONARCH_PASSWORD と組み合わせて使用します）。	(なし)
MONARCH_PASSWORD	いいえ	環境変数によるログイン用のパスワードです。	(なし)
MONARCH_TOTP	いいえ	TOTP コードです（2FA が有効な場合のみ）。	(なし)
MONARCH_EMAIL_OTP	いいえ	メール OTP コードです（新規インストールからの初回ログイン時のみ）。	(なし)
MONARCH_SESSION_PASSPHRASE	いいえ	ディスク上のセッションファイルに使用する暗号化パスフレーズを上書きします。	monarch-mcp:${HOSTNAME}:${USER}
MONARCH_STATE_DIR	いいえ	session.enc が保存されるディレクトリを上書きします。	~/.monarch-money-mcp
MONARCH_ENABLED_TOOL_GROUPS	いいえ	公開するグループのカンマ区切りリストです（readonly、manage）。デフォルトではすべてのグループが対象です。	(すべて)
MONARCH_ENABLED_TOOLS	いいえ	ツール名のカンマ区切りの許可リストです。設定すると、グループと無効化リストより優先されます。	(なし)
MONARCH_DISABLED_TOOLS	いいえ	ツール名のカンマ区切りの拒否リストです。グループによるフィルタリング後に、指定したツールを除外します。	(なし)

セキュリティに関する考慮事項

• MCP ツール経由でパスワードを入力しないでください。 認証は CLI ログインスクリプトまたは環境変数を通じて行われ、ツール入力を通じて行われることはありません。ツール入力はトランスクリプトやプロンプトキャッシュに残る可能性があるため、パスワードを入力してはいけません。
• セッションファイルは AES-256-GCM で保存時に暗号化されます。 デフォルトのパスフレーズ（ホスト＋ユーザー）により、ファイルは書き込み元のマシンに紐付けられます。
• ツールグループのフィルタリングが、主な書き込み保護の仕組みです。 厳格な読み取り専用のデプロイでは、MONARCH_ENABLED_TOOL_GROUPS=readonly を設定してください。
• 読み取りツールには制限がありません。 セッションのロックを解除すると、アカウントや取引データを制限なく読み取れます。読み取り側にも承認を必要とする場合は、ツール呼び出しを独自の確認フローでラップするクライアントの背後でサーバーを実行してください。

開発

プロジェクト構成

monarch-money/
├── local/                   # Stdio entry point
│   └── src/
│       ├── index.ts                       # Production entry
│       └── index.integration-with-mock.ts # Integration test entry
├── shared/                  # Business logic
│   └── src/
│       ├── server.ts        # MCP server factory
│       ├── tools.ts         # Tool registration glue + group filtering
│       ├── tools/           # One file per tool group
│       ├── monarch-client/  # GraphQL transport + session store
│       └── types.ts
├── scripts/
│   └── login.ts             # Email/password/TOTP CLI flow
└── tests/
    ├── functional/          # Unit tests with mocked client
    ├── integration/         # Full MCP protocol with mocked Monarch
    └── e2e/                 # Hits the real Monarch GraphQL API

テストの実行

# From this directory:
npm test                  # Functional tests
npm run test:integration  # Integration tests (builds first)
npm run test:e2e          # E2E tests (requires MONARCH_SESSION_TOKEN)

ライセンス

MIT