monzo-mcp

monzo-mcp

Monzo 銀行 API 用の MCP サーバーです。Claude Code または任意の MCP クライアントを通じて、口座、残高、ポット、取引、支出分析に読み取り専用でアクセスできます。

生のベアラートークンを使用する他の Monzo MCP 実装とは異なり（トークンの有効期限は 6 時間です）、このサーバーはトークンの自動更新を含む完全な OAuthに対応しています。

特長

• 読み取り専用ツール 7 種類 - 書き込み操作や資金移動はありません
• 自動更新対応 OAuth - トークンは自動で更新されるため、手動で再生成する必要はありません
• ローカル取引キャッシュ - SQLite データベースにより、Monzo の 90 日間の SCA ウィンドウを超えてデータを保持します
• 必要に応じた自動同期 - キャッシュ読み取りツールは、当日まだ同期されていない場合に差分同期を自動実行するため、手動で monzo_sync を呼び出す必要はほとんどありません
• 支出分析 - カテゴリー別の内訳、主要加盟店、前月との比較
• 取引検索 - キャッシュされた履歴から、加盟店、受取人（取引相手）、説明、メモで検索できます
• 取引相手の詳細情報 - 銀行振込（高速決済、P2P、Bacs）は、受取人の氏名、ソートコード、口座番号とともにキャッシュされます

ツール

ツール	説明	データソース
monzo_list_accounts	種類と ID を含む口座一覧	ライブ API
monzo_get_balance	現在の残高と本日の支出	ライブ API
monzo_list_pots	貯蓄ポットと残高	ライブ API
monzo_sync	取引をローカルキャッシュに同期	ライブ API -> SQLite
monzo_list_transactions	キャッシュされた取引の一覧表示／絞り込み	ローカルキャッシュ（古い場合は自動同期）
monzo_search_transactions	加盟店／受取人／説明／メモで検索	ローカルキャッシュ（古い場合は自動同期）
monzo_spending	カテゴリー別内訳を含む支出分析	ローカルキャッシュ（古い場合は自動同期）

前提条件

• Python 3.13+（CI で Linux、macOS、Windows 上の 3.13 および 3.14 をテスト済み）
• uv（推奨）または pip
• developers.monzo.com で OAuth クライアントを登録した Monzo アカウント

インストール

git clone https://github.com/partymola/monzo-mcp.git
cd monzo-mcp
uv venv --python 3.13 .venv
uv pip install -e .

このパッケージは PyPI にはありません。名称は無関係な別のプロジェクトが使用しています。代わりにコンテナーイメージを公開しています。詳しくはDockerをご覧ください。

セットアップ

1. Monzo OAuth クライアントを登録する

developers.monzo.com にアクセスし、OAuth クライアントを作成します。

• リダイレクト URL を http://localhost:6600/callback に設定します
• Client ID と Client Secret を控えておきます

2. 認証する

monzo-mcp auth

Monzo OAuth のためにブラウザーが開きます。認証後、5 分以内にMonzo アプリでログインを承認すると、取引履歴全体にアクセスできます（Monzo の SCA ウィンドウ）。

3. Claude Code に登録する

claude mcp add -s user monzo -- /path/to/monzo-mcp/.venv/bin/monzo-mcp

Windows では、コンソールスクリプトは .venv\Scripts\monzo-mcp.exe にあります。

4. 初回同期

Claude Code で monzo_sync を実行し、取引キャッシュを作成します。SCA ウィンドウを活用するため、認証後すぐに実行してください（最大 11 か月分の履歴を取得できます）。

Docker

イメージは ghcr.io/partymola/monzo-mcp に公開されています。タグには v プレフィックスが付き（:vX.Y.Z）、:latest は最新リリースを指します。

コンテナにはボリュームが必要です。 認証情報と取引キャッシュは /data に保存されます。ここに何もマウントしなくてもコンテナは起動しますが、すべてのツールが未設定であると報告し、認証した内容もコンテナを置き換えると失われます。

まず、セットアップ手順 1 の説明に従って OAuth クライアントを登録します。auth はクライアント ID とシークレットの入力を求めます。後からこれらを指定する方法はありません。リダイレクト URL は、ソースからのインストールと同じ http://localhost:6600/callback です。

名前付きボリュームを使って、認証を一度行います。実行する前に、代わりにバインドマウントを使うかどうかを決めてください。後から切り替える場合は、再認証が必要です。

docker volume create monzo-mcp-data
docker run --rm -it \
  -v monzo-mcp-data:/data \
  -p 127.0.0.1:6600:6600 \
  ghcr.io/partymola/monzo-mcp:latest auth

公開ポートが必要なのはこの手順だけです。OAuth リダイレクトがコンテナに到達できるようにします。127.0.0.1 にバインドすると、コールバックリスナーがネットワークに公開されません。ブラウザーは開きません。コンテナにはブラウザーがないため、表示された URL をコピーしてください。その後、5 分以内に Monzo アプリでログインを承認します（Monzo SCA の有効時間を参照）。

次に、同じボリュームを再利用してサーバーを登録します。

claude mcp add -s user monzo -- \
  docker run --rm -i -v monzo-mcp-data:/data ghcr.io/partymola/monzo-mcp:latest

-i は必須です。サーバーは stdin と stdout を介して JSON-RPC を使用します。

すぐに同期してください。 Monzo アプリで承認してから 5 分後に、11 か月分のバックフィルができなくなります（Monzo SCA の有効時間を参照）。また、この方法はソースからのインストールより手順が長いため、サーバーの登録後すぐに monzo_sync を呼び出してください。間に合わないと、エラーが表示されないまま、代わりに 90 日分しか取得できなくなります。

ファイルを読み取り可能な場所に保存するには、名前付きボリュームの代わりにバインドマウントを使用します。コンテナは root として実行され、認証情報は所有者のみが読み取り可能な状態で書き込まれるため、--user を指定しないと root 所有になります。

mkdir -p ~/monzo-mcp-data/config
docker run --rm -it \
  -v ~/monzo-mcp-data:/data \
  --user $(id -u):$(id -g) \
  -p 127.0.0.1:6600:6600 \
  ghcr.io/partymola/monzo-mcp:latest auth

サーバーのコマンドにも同じ -v と --user を指定してください。先にディレクトリを作成してください。名前付きボリュームに対して --user を指定すると、イメージから root 所有で初期化されるため失敗します。

CLI

monzo-mcp              Start the MCP server (stdio transport)
monzo-mcp auth         Interactive OAuth setup (opens the browser)
monzo-mcp --version    Print the installed package version

設定

すべての設定は環境変数で行います（任意）。

変数	デフォルト	説明
MONZO_MCP_CONFIG_DIR	<package>/config/	OAuth 認証情報とトークンの保存ディレクトリ
MONZO_MCP_DB_PATH	<package>/monzo.db	SQLite 取引キャッシュへのパス
MONZO_MCP_CALLBACK_HOST	localhost	auth コールバックサーバーがバインドするインターフェース。リダイレクト URI には影響しません

コンテナイメージでは、最初の 2 つの変数を /data 以下に設定しています。パッケージ相対のデフォルト値では、マウントできないインタープリターの lib ディレクトリ内に解決されるためです。また、公開ポートへの接続はコンテナのブリッジインターフェースに届き、localhost へのバインドでは接続が拒否されるため、3 つ目の変数を 0.0.0.0 に設定しています。

認証情報ファイル（monzo-mcp auth が作成）：

• config/monzo_client.json - OAuth クライアント ID とシークレット
• config/monzo_tokens.json - アクセストークンとリフレッシュトークン（自動更新）

Monzo SCA の有効時間

Monzo の強力な顧客認証（SCA）により、取引履歴へのアクセスが制限されます。

• アプリでの承認から 5 分以内：最大約 11 か月分の履歴
• 有効時間の経過後：直近 90 日分のみ

ローカルの SQLite キャッシュには、同期したすべての取引が永続的に保存されるため、monzo-mcp auth の後、速やかに monzo_sync を実行してください。

特定の期間をバックフィルするには、monzo_sync に since を渡します。ISO 日付（2026-01-01）または日時（2026-01-01T14:30:00Z）を指定できます。直近 90 日以内であれば、いつでも実行できます。それより前まで遡れるのは SCA の有効時間内に限られます。有効時間外ではリクエストが拒否され、同期ではエラーなしに、キャッシュ内の最新の取引より新しいデータのみが取得されます。

古いキャッシュ済み取引に新しいバージョンで追加されたフィールド（銀行振込の取引相手／受取人の詳細など）が追加されるのは、再取得した場合のみです。認証後の全件同期では、再取得対象の履歴についてこれらのフィールドが追加されます。

セキュリティ

• 書き込みツールはありません - 送金、ポット間の資金移動、取引の変更はできません
• Monzo API 自体は外部口座に送金できません
• トークンは config/ ディレクトリ内の JSON ファイルとして保存されます（gitignore 対象）
• すべての API 呼び出しは、Bearer トークン認証を使った GET リクエストです

トラブルシューティング

• 「SCA required」と表示される、または90日分の履歴しか取得できない - monzo-mcp auth を再実行し、5分以内に Monzo アプリでログインを承認してから、すぐに同期してください（上記の SCA 有効期間を参照）。
• トークンの期限切れ／更新されない - monzo-mcp auth を再実行して、再認証してください。
• 「No transaction data available」と表示される - キャッシュが空です。認証後に一度 monzo_sync（またはキャッシュを読み取るツール。自動的に同期されます）を呼び出してください。
• Docker で各ツールが「not configured」と報告する、または再起動後に認証状態が保持されない - /data に何もマウントされていません。Docker を参照してください。auth の実行時とサーバーの起動時に、同じボリュームを渡す必要があります。
• 承認後も auth が「Waiting for callback...」のままになる - コールバックが届いていません。Ctrl-C を押して、もう一度実行してください。Docker の場合、ポートが公開されていることを確認してください（-p 127.0.0.1:6600:6600）。

コントリビュート

開発環境のセットアップ、テストのワークフロー、プリコミットフックについては CONTRIBUTING.md を参照してください。変更内容は CHANGELOG.md で追跡されています。

ライセンス

GPL-3.0-or-later。LICENSE を参照してください。