NZ Open Banking MCP (Akahu)

新しい相手に銀行の認証情報を渡すことなく、ニュージーランドの銀行口座について AI アシスタントに質問できます。nz-openbank-mcp は、Akahu と通信する Model Context Protocol サーバーです。Akahu はニュージーランドのオープンファイナンスサービスで、ユーザー自身が作成・管理する Personal App を使用します。ご自身のマシン上で動作し、初期状態では読み取り専用で、何かを変更する前に確認を求めます。

非公式です。Akahu またはいずれの銀行とも提携しておらず、承認も受けていません。

質問してみましょう

• 「先月、食料品にいくら使いましたか？どのお店で使いましたか？」
• 「どのサブスクリプションに支払っていますか？年間の費用はいくらですか？」
• 「すべての口座の残高を表示してください。」
• 「今年、家主への支払いをすべて探してください。」
• 「まだ決済されていない保留中の取引はありますか？」
• 「9 月と 10 月の外食費を比較してください。」

試しても安全な理由

デフォルトで読み取り専用	AKAHU_READ_ONLY=false を設定するまで、書き込みツールは拒否されます。
書き込みごとに同意を確認	書き込みを有効にすると、書き込みのたびに事前に確認があり、送信内容が正確に表示されます。
ローカルでプライベート	お使いのマシン上で stdio 経由で実行され、通信先は api.akahu.io のみです。トークンや取引内容がログに記録されることはありません。
口座番号をマスキング	表示されるのは銀行コード、下4桁、接尾辞のみです。
小規模でテスト済み	Akahu エンドポイントを呼び出す薄いラッパーで、厳密な型付けを採用しています。CI では行カバレッジと分岐カバレッジ100％を必須としています。

PyPI · リリース · セキュリティポリシー

できること

サーバーは14個のツールを公開します。10個は読み取り専用で、何かを変更する4個は、書き込みを有効にするまでオフになっています。

全14個のツール

ツール	書き込み？	目的
acct_list_accounts		接続されているすべての口座を、マスキングされた番号と残高とともに表示します
acct_get_account		IDで指定した1つの口座を表示します
acct_get_account_balance		1つの口座の残高のみを表示します
acct_get_pending_transactions		1つの口座の未確定取引を表示します
txn_get_transactions		口座、日付、カテゴリ、金額で絞り込んだ確定済み取引を表示します（デフォルトは100件）
txn_get_transaction		IDで指定した1つの取引を表示します
txn_get_transactions_by_ids		1回のリクエストで複数の取引を表示します
txn_get_pending_transactions		すべての口座の未確定取引を表示します
txn_search_transactions		摘要と加盟店を大文字・小文字を区別せずに検索します。開始日を指定しない場合、終了日または今日までの90日間が対象です（デフォルトは50件）
id_get_me		Akahu ユーザーのプロフィールを表示します
acct_refresh_all_accounts	はい	Akahu にすべての口座の最新データを取得するよう依頼します
acct_refresh_account	はい	Akahu に1つの口座の最新データを取得するよう依頼します
txn_report_transaction_issue	はい	取引について Akahu にサポートチケットを作成します
id_verify_name	はい	口座名義人と照合して名前を確認します。追加のスコープが必要です（制限事項を参照）。呼び出しごとに料金が発生する場合があります

支出レポート、予算、予測の機能は組み込まれていません。アシスタントは取引データからこれらを算出するため、サーバーを小規模に保ち、監査しやすくしています。

Akahu トークンを取得する

1. my.akahu.nz/developers にサインインし、Personal App を作成します。
2. アシスタントに表示させたい銀行口座を接続します。
3. App Token（app_token_...）と User Token（user_token_...）をコピーします。

どちらもパスワードと同様に扱ってください。以下のインストール手順では、これらがプロジェクトファイルに保存されないようにします。

uv も必要です。プラグイン、Desktop Extension、汎用クライアントのセットアップでは、いずれも uvx でサーバーを実行します。uvx はリリースと対応する Python を取得します。

インストール

使用する場所	方法	トークンの保存場所
Claude Code	このリポジトリのマーケットプレイスからプラグインをインストール	OS のキーチェーン。インストール時に入力します
Claude Desktop	.mcpb Desktop Extension	OS のキーチェーン。インストール時に入力します
Codex	このリポジトリのマーケットプレイスからプラグインをインストール	Codex の起動時に使用する環境
Cursor	このリポジトリのマーケットプレイスからプラグインをインストール	Cursor のプラグイン設定
Grok Build	このリポジトリのマーケットプレイスからプラグインをインストール	Grok の起動時に使用する環境
claude.ai、ChatGPT、grok.com	OAuth を使用するセルフホスト可能な HTTPS サーバー	お使いのサーバーの環境
MCP に対応するその他のもの	uvx nz-openbank-mcp	クライアントの環境

以下のどの方法でも、AKAHU_READ_ONLY=true と AKAHU_AUTOMATION_BYPASS=false を設定して開始します。

Claude Code

/plugin marketplace add thatskiff33/nz-openbank-mcp
/plugin install nz-openbank-mcp@nz-openbank

Claude Code では、トークンと 2 つの安全設定を入力します。続いて /mcp を実行すると、サーバーが接続済みとして表示されます。後から設定を変更するには、/plugin を開き、プラグインを選択して Configure options を選びます。更新や削除などの詳細については、plugin/README.md を参照してください。

Claude Desktop

最新リリースから nz-openbank-mcp-X.Y.Z.mcpb をダウンロードして開くか、Settings -> Extensions -> Advanced -> Install Extension を使用します。Desktop にトークンと設定を入力するフォームが表示されます。更新するには、新しい .mcpb をインストールします。

Claude Code プラグインは Claude Desktop では動作しません。Desktop はまだプラグイン設定を収集できないためです。

Codex, Grok Build

どちらのホストもプラグインのシークレットを入力するよう求めることができないため、トークンはホストの起動時に使われる環境から取得します。ドットファイルに書き込むのではなく、OS のシークレットストアから読み取ってください。

# macOS
export AKAHU_USER_TOKEN="$(security find-generic-password -s akahu-user-token -w)"
export AKAHU_APP_TOKEN="$(security find-generic-password -s akahu-app-token -w)"
# Linux (libsecret)
export AKAHU_USER_TOKEN="$(secret-tool lookup service akahu-user-token)"
export AKAHU_APP_TOKEN="$(secret-tool lookup service akahu-app-token)"

Codex、Grok Build、Cursor では、ホストの起動時に使われる環境に AKAHU_READ_ONLY または AKAHU_AUTOMATION_BYPASS がすでに設定されていると、安全なデフォルト設定が上書きされます。

Codex：

codex plugin marketplace add thatskiff33/nz-openbank-mcp
codex plugin add nz-openbank-mcp@nz-openbank
codex mcp list          # shows the akahu server

Codex は、4 つの AKAHU_* 設定のみをサーバーに渡します。codex plugin marketplace upgrade nz-openbank で更新します。

Grok Build：

grok plugin marketplace add thatskiff33/nz-openbank-mcp
grok plugin install nz-openbank-mcp --trust
grok mcp doctor akahu   # should report 14 tools

Grok は Claude Code プラグインも読み込みます。サーバーが 2 つ起動してしまうため、どちらか一方にのみインストールしてください。

Cursor

agent plugin marketplace add https://github.com/thatskiff33/nz-openbank-mcp

Customize（または Cursor CLI の /plugins）から nz-openbank-mcp をインストールし、Plugins -> Configure で 2 つのトークンを入力します。トークンはリポジトリではなく Cursor に保存されます。デフォルト設定を維持するには、安全設定を空欄のままにします。サーバーは plugin-nz-openbank-mcp-akahu として表示されます。ここで未設定の設定は、Cursor の起動時に使われる環境の値にフォールバックします。ローカルのチェックアウトを試すには、--plugin-dir /path/to/nz-openbank-mcp/plugin を指定して Cursor CLI を起動します。

上部の Add to Cursor ボタンを使うと、プラグインではなく通常の MCP エントリーがインストールされます。このエントリーは、Cursor の起動時に使われる環境から AKAHU_USER_TOKEN と AKAHU_APP_TOKEN を読み取るため、上記の Codex の説明に従って設定してください。

Web コネクター（claude.ai、ChatGPT、grok.com）

Web アシスタントが接続できるのは、パブリックインターネット上のサーバーのみです。nz-openbank-mcp-http エントリーポイントを OAuth を使って HTTPS の背後で実行し、アシスタントにカスタムコネクターを追加して、サーバーの /mcp URL を指定します（grok.com の場合は grok.com/connectors）。OAuth モードでは、このサーバーが OAuth 認可サーバーとして動作し、Google がサインインするユーザーを確認します。許可した Google アカウントまたは Workspace ドメインのみがアクセスできます。Google に Akahu トークンが渡ることはありません。

セットアップ、Google クライアント、リダイレクト許可リスト、セキュリティ強化については、docs/public-https-streamable-http.md を参照してください。deploy/linux-systemd/ には systemd の例があります。grok.com のコネクターコールバック https://grok.com/connectors-oauth-exchange-code/ は、デフォルトのリダイレクトリストに含まれていません。NZ_OPENBANK_MCP_ALLOWED_REDIRECT_URIS はリスト全体を置き換えるため、引き続き必要なデフォルトのエントリーも一緒に含めてください。

その他の MCP クライアント

クライアントで以下のコマンドを指定し、設定を環境変数として渡してください。

uvx nz-openbank-mcp            # or pin: uvx --from nz-openbank-mcp==X.Y.Z nz-openbank-mcp

examples/claude_desktop_config.json には、JSON で設定する多くのクライアントが想定する形式が示されています。拡張機能ではなく Claude Desktop で使用するには、これを設定ファイルにマージして再起動してください。

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

Docker

各リリースはマルチアーキテクチャイメージ（amd64 と arm64）としても公開されており、 非 root ユーザーで実行し、読み取り専用モードが有効になっています。

docker run -i --rm -e AKAHU_USER_TOKEN -e AKAHU_APP_TOKEN ghcr.io/thatskiff33/nz-openbank-mcp

値を指定せずに -e NAME を指定すると、シェルから変数が引き継がれるため、トークンがコマンドラインに表示されません。JSON で設定するクライアントでは、これらの引数とともに "command": "docker" を指定します。HTTP サーバーの場合は、イメージ内で nz-openbank-mcp-http を実行してください。HTTPS ガイドを参照してください。

設定

サーバーはプロセスの環境変数から設定を読み込み、AKAHU_ENV_FILE で指定された場合に限り env ファイルも読み込みます（プロセスの値が優先されます）。作業ディレクトリにある .env ファイルは読み込みません。

変数	デフォルト	説明
AKAHU_USER_TOKEN	（必須）	ユーザートークン
AKAHU_APP_TOKEN	（必須）	Personal App の App Token
AKAHU_READ_ONLY	true	すべての書き込みツールを拒否します
AKAHU_AUTOMATION_BYPASS	false	2 つの更新ツールで確認プロンプトを省略します
AKAHU_REQUEST_TIMEOUT	10	Akahu リクエストごとのタイムアウト秒数（1～120）
AKAHU_LOG_LEVEL	INFO	DEBUG、INFO、WARNING、ERROR、CRITICAL のいずれか
AKAHU_ENV_FILE	（未設定）	読み込む env ファイルの絶対パス。Linux と macOS では、自分または root が所有し、グループやその他のユーザーが書き込み可能でないファイルである必要があります
AKAHU_BASE_URL	https://api.akahu.io/v1	次の設定が有効でない限り、api.akahu.io のままにする必要があります
AKAHU_ALLOW_CUSTOM_BASE_URL	false	別の API ホストを許可します。プロセス環境からのみ有効で、env ファイルからは有効になりません

カスタム API ホストが使用されている場合、サーバーは起動時に警告をログに記録します。AKAHU_ENV_FILE と AKAHU_ALLOW_CUSTOM_BASE_URL は、自分のシェルまたはホスト設定にのみ指定してください。クローンしたリポジトリのプロジェクトファイルには指定しないでください。

HTTP エントリーポイントには独自の NZ_OPENBANK_MCP_* 設定があります。これらは .env.example と HTTPS ガイドに記載されています。

書き込みの保護方法

すべての書き込みツールの前に、3 つのチェックが行われます。

1. 読み取り専用スイッチ。 AKAHU_READ_ONLY=true の場合、リクエストがマシンの外に送信される前にツールが拒否します。
2. 確認。 書き込みが有効な場合、サーバーはアシスタントの確認プロンプトを通じて、呼び出しごとに承認を求めます。プロンプトには、サポートチケットのコメント全文など、送信されるすべての値が引用符で囲まれて表示され、隠し文字も見える形になります。1,000 文字を超える値は短縮せずに拒否されます。確認を断るか、プロンプトを閉じると、呼び出しはキャンセルされます。
3. 限定的なバイパス。 AKAHU_AUTOMATION_BYPASS=true の場合、acct_refresh_all_accounts と acct_refresh_account の確認プロンプトのみ省略されます。これらのツールは Akahu に再同期を依頼するだけです。省略されたプロンプトはすべてログに記録され、起動時のバナーにこれらのツールが表示されます。また、読み取り専用が有効な状態ではバイパスを有効にしてサーバーを起動できません。サポートチケットと名前の照合では、常に確認が求められます。

制限事項

Akahu Personal Apps からはアプリ単位のエンドポイントにアクセスできないため、このサーバーにはカテゴリー（取引データに含まれています）、対応銀行の一覧、支払い、Webhook 用のツールはありません。

id_verify_name には、my.akahu.nz/developers で Personal App に対して有効にするスコープが必要です。スコープがない場合、Akahu は 403 を返します。

保留中の取引には ID がなく、確定前に変更されることがあり、"pending": true として示されます。

txn_get_transactions と txn_search_transactions は、Akahu からの結果を呼び出しごとに最大 20 ページまで読み込みます。期間内の結果がそれを超える場合、結果には "truncated": true が含まれます。日付範囲を狭めて再度リクエストしてください。

読み取りとアカウントの更新では、ネットワークエラーと Akahu サーバーエラーが発生した場合、最大 3 回まで再試行されます。タイムアウトしたリクエストが Akahu に到達している可能性があるため、サポートチケットと名前の照合は 1 回だけ送信されます。レート制限（429）への応答は、すべてのリクエストで再試行されます。

日付と金額

Akahu は UTC のタイムスタンプを保存しますが、日付はニュージーランドの暦日（Pacific/Auckland）です。start_date=2026-10-18 のような日付のみのフィルターは、範囲の開始日と終了日のどちらでも、そのニュージーランドの一日全体を対象とします。完全な ISO 8601 タイムスタンプは変更せずに Akahu に渡され、オフセットのないものは Akahu によって UTC として扱われます。金額は各口座の通貨で表示されるため、USD 口座では -USD 9.99 のようになります。口座の通貨が不明な場合、currency は null になり、amount には通貨記号が付きません（例：-1,234.50）。amount_raw は同じ金額を小数点以下 2 桁に丸めた数値です。その他の日付形式は拒否されます。

プライバシー

• ニュージーランドの口座番号は、銀行コード、口座番号の下 4 桁、サフィックスを残してマスキングされます。その他の形式では、末尾 4 桁を除くすべての数字がマスキングされます。
• トークンがログに記録されることはありません。残高や取引内容もログに記録されません。Akahu の口座 ID や取引 ID が含まれる場合のあるリクエストパスは、ステータスとともに記録されます。
• デフォルトでは、stdio 経由の場合、サーバーのネットワーク通信先は api.akahu.io のみです（パッケージをダウンロードする uvx を除く）。HTTP モードでは、サインインのために Google への通信が追加されます。
• 口座と日付のフィルターは Akahu に送信され、カテゴリーと金額のフィルターはデータの取得後に適用されます。Personal Apps には、より細かなアクセス制御がありません。そのため、トークンは接続したすべてのデータを読み取れます。

プライバシーポリシーでは、誰が何を閲覧できるかを説明しています。脅威モデルでは、各リスクとその緩和策、および残るリスクを一覧にしています。

リリースファイル（wheel、sdist、.mcpb）には GitHub ビルドの来歴情報が含まれており、PyPI へのアップロードには Trusted Publishing を使用しています。ダウンロードを確認するには、次の手順を実行してください。

gh attestation verify nz-openbank-mcp-X.Y.Z.mcpb --repo thatskiff33/nz-openbank-mcp

脆弱性は SECURITY.md から非公開で報告してください。

開発

git clone https://github.com/thatskiff33/nz-openbank-mcp.git
cd nz-openbank-mcp
uv sync --extra dev
uv run pytest                 # 100% line and branch coverage is required
uv run ruff check . && uv run mypy src
FASTMCP_ENV_FILE=/dev/null uv run fastmcp dev src/nz_openbank_mcp/server.py

Claude Code からローカルのチェックアウトを使用するには、次の手順を実行してください。

claude mcp add nz-openbank --scope user \
  --env AKAHU_APP_TOKEN=app_token_... --env AKAHU_USER_TOKEN=user_token_... \
  -- uv --directory "$(pwd)" run nz-openbank-mcp

ホストのプラグインマニフェストは自動生成されます。plugin/plugin.base.toml を編集してから、uv run --no-project python scripts/sync_plugin_manifests.py を実行してください。リリースについては PUBLISHING.md をご覧ください。その他の運用ガイドは docs/ にあります。

コントリビューションを歓迎します。CONTRIBUTING.md、行動規範、変更履歴をご覧ください。質問はディスカッションでお寄せください。

ライセンスと免責事項

Apache-2.0 ライセンスで提供されています。詳細は LICENSE をご覧ください。nz-akahu-mcp（severity1、Apache-2.0）をもとに大幅に変更しています。詳細は NOTICE をご覧ください。このプロジェクトは、severity1 がオリジナルを開発し、オープンソースとして公開してくれたおかげで実現しました。severity1 に感謝します。

このソフトウェアは現状有姿で提供されます。金融データとともに本ソフトウェアをどのように使用するかは、利用者の責任です。メンテナーは、本ソフトウェアの使用によって生じるデータ損失、不正アクセス、金銭的損失について、一切の責任を負いません。