monarch-mcp2-obot

obot の背後でセルフホスティングするためのシングルテナントの Monarch Money MCP サーバーです。erikrubstein/monarch-mcp2 からフォークしました(これは、よく見かける robcerda/monarch-mcp-server 系のフォークではなく、独自の API クライアントである monarch-api2 を基盤にした独立した実装です)。

このフォークが存在する理由は、アップストリームがカバーしていなかった次の3つです。

1. MCP Python SDK v2 への移植(非推奨の v1 FastMCP ではなく MCPServer を使用)。

2. obot 向けに作られたログインワークフロー: 認証情報を環境変数として一度設定するだけで、オプションの TOTP シード対応により認証アプリの MFA チャレンジを自動的に解決できます。ブラウザも OS キーリングも、6桁のコードを手でコピーする必要もありません。

3. 意図的なシングルテナント: 実行中のインスタンスごとに正確に1つの Monarch アカウントのみ。クライアントが送信しようとした場合でも、どのツール呼び出しも別のアカウントのセッションを対象にできません — 下記の「シングルテナント(意図的)」を参照してください。

Monarch Money とは提携関係がなく、Monarch Money からの承認やサポートを受けていません。

アップストリームから引き継いだもの

14グループにわたる125のツール — accounts、transactions、budget、cashflow、categories、goals、household、investments、merchants、receipts、recurring、reports、tags — は monarch-mcp2 から変更なしで引き継いでいます。対象範囲と意図的にスコープ外としたもの(取引ルールと自動化、プロバイダーアカウントの接続フロー、アカウント管理のエッジケース)については、ツール一覧 と 設計ノート を参照してください。

Related MCP server: monarch-mcp

ここでの変更点

認証: auth_login, auth_status

アップストリームの auth_create_session / auth_save_session / auth_load_session(完全手動の一回限りのログイン用に引き続き動作します)に加えて、新しいツールが2つあります。

• auth_login — サーバーの環境に MONARCH_EMAIL / MONARCH_PASSWORD(および認証アプリの MFA 用に MONARCH_TOTP_SECRET)が設定されていれば、引数は不要です。シードから現在のコードを計算することで、MFA チャレンジを自動的に処理します。email / password / totp_secret / mfa_code を明示的に渡すと、サーバー設定を変更せずに一回限りのログインを上書きできます。

• auth_status — セッションが存在し、現在も有効かどうかを報告します(デフォルトでは軽量な API 呼び出しを1回行うだけです)。セッショントークンを一切返すことはありません。

サーバーはまた、認証情報が設定されている場合、起動時にこのログインを自動的に試みます。これはベストエフォートであり、失敗しても致命的ではありません。パスワードの誤りやネットワーク障害によってサーバーが起動できなくなることはありません。診断と再試行には auth_status と auth_login が引き続き利用できます。

TOTP シード: 認証アプリに登録するのと同じ base32 シークレットです(QR コードとしてスキャンするものです)。Monarch は認証アプリの MFA を有効にしたときにこれを一度だけ表示するので、その場で保存してください。保存しないと、新しいシードを取得するには MFA を無効化して再有効化する必要があります。これは、アカウントの MFA 方式が認証アプリの場合にのみ当てはまります。メールコード式 MFA はこの方法では自動化できません(コードを計算するためのシードがないため)。新しいコードを auth_login の mfa_code 引数で中継する人間が依然として必要です。

シングルテナント(意図的)

session_path はすべての基盤関数に存在します(monarch-api2 の慣例)が、MCP クライアントに公開される前にすべてのツールの公開スキーマから取り除かれます — tool_metadata.py を参照。1つのデプロイ、1つの Monarch アカウント、1つのセッションファイル。これらは MONARCH_SESSION_PATH / MONARCH_CONFIG_DIR で一度だけ選択されます。これは単なる設定のデフォルトではありません。設計上、クライアントが送信した場合でも、どのツール呼び出しもリクエスト単位でこれを上書きできません(tests/test_server.py::test_tool_call_ignores_session_path_even_if_a_client_sends_it を参照)。

obot の2つのデプロイモデルに対応するトランスポート選択

obot は MCP サーバーを、ここに関連する2つの方法でサポートしています: コマンド / uvx ベース(stdio)と Docker ベース(ポートと streamable-http エンドポイント)です。どちらも MCP_TRANSPORT でサポートされています(デフォルトは stdio)。Docker イメージはデフォルトでこれを streamable-http に設定します。config.py / server.py を参照してください。

環境変数

MONARCH_PASSWORD と MONARCH_TOTP_SECRET は、他のシークレットと同様に扱ってください。obot のシングルユーザー MCP サーバーモデルは、管理者がサーバーを構成するときにこのようなフィールドを "sensitive" とマークします。それを利用してください。

実行方法

obot、コマンド / uvx ベース(stdio)

uvx --from git+https://<your-fork-url> monarch-mcp

(このフォークをどこかのリモートにプッシュしたら — このコードが現在どこにあるかについては、この README の最後にある注記を参照してください。)

obot、Docker ベース(streamable-http)

docker build -t monarch-mcp2-obot:local .
docker volume create monarch-session

docker run -d --rm \
  -p 8000:8000 \
  -v monarch-session:/data \
  -e MONARCH_EMAIL=you@example.com \
  -e MONARCH_PASSWORD=... \
  -e MONARCH_TOTP_SECRET=...  `# omit if your account doesn't use authenticator-app MFA` \
  monarch-mcp2-obot:local

obot の Docker ベースの MCP サーバー設定で、このコンテナの streamable-http エンドポイント(ポート8000)を指定してください。セッション状態は monarch-session ボリュームに保存されるため、コンテナの再起動や再デプロイ後も、再ログインなしで維持されます。

ローカル開発(stdio、Docker なし)

uv sync
uv run monarch-mcp

テスト

uv run pytest
uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy src/monarch_mcp/auth_runtime.py src/monarch_mcp/config.py \
  src/monarch_mcp/server.py src/monarch_mcp/groups/auth.py src/monarch_mcp/tool_metadata.py

(mypy --strict は、このフォークが作成または大幅に変更したファイルに限定されています。引き継いだグループモジュールは、このフォークの一環として厳密な型付けの再監査は行われていません — ROADMAP.md を参照。)

このコードの所在

これはローカルでビルドおよび検証されました(インストール、テスト、実行 — 両トランスポート — を実際の MCP initialize ハンドシェイクに対して実施)。ただし、この作業の一環として、ホストされている git リモートへのプッシュは行われていません。uvx --from git+... で参照する前に、自分のフォーク / リモートにプッシュしてください。また、ローカルチェックアウトではなくそのリモートからビルドする場合は、上記の Docker ビルド手順をそれに合わせて更新してください。

ライセンス

MIT。アップストリームから引き継いでいます。LICENSE を参照してください。