MainBook Bank Statement Converter

MainBook 銀行明細変換ツール

PDF の銀行明細を検証済みの JSON、Excel、または CSV に変換することに特化した金融向け MCP サーバーです。汎用的な会計用 MCP ではありません。 mainbook-mcp auth login を一度実行すればローカルで動作します。または、クライアントから MainBook アカウントでサインインする、MainBook のホステッドエンドポイント https://mcp.mainbook.ai/mcp を利用できます。既存の mb_live_ API キーも、スクリプトや旧バージョンのクライアントで引き続き使用できます。

アシスタントに明細を渡して、スプレッドシートを作成するよう依頼してください。PDF は MainBook に送信され、すべての取引が抽出されます。日付は YYYY-MM-DD に正規化され、金額は正確な値のまま保持されます。また、明細の合計を再計算し、opening balance + credits − debits が期末残高と一致することを確認します。一致しない行は、通知されずに処理が進むのではなく、フラグが付けられます。

> Convert ~/Downloads/march-statement.pdf and save the Excel next to it.

  mainbook - convert_bank_statement (MCP)
  63 transactions · 4 pages · 4 credits
  Totals reconciled against the statement
  Saved to ~/Downloads/march-statement.xlsx

Done — 63 transactions. Opening 4,127.50 and closing 3,881.05 both match
the statement, and nothing was flagged.

これは何ではないか

銀行口座には接続せず、Open Banking や銀行データの API でもありません。お手元にある明細ファイルを読み取ります。スクレイピングは行わず、銀行の認証情報も必要ありません。

必要なもの

MainBook アカウントと、明細を保存しているフォルダーが必要です。ページクレジットを消費するのは変換ツールのみです。残りの 4 つのうち、get_balance と list_conversions は読み取りのみ、get_conversion は結果ファイルを書き込む場合があり、output_folder はローカルの設定を変更します。これらが MainBook アカウント内の情報を変更することはありません。

クライアントに追加する

ターミナルから一度サインインします。

uvx mainbook-mcp auth login

このコマンドはブラウザーで MainBook を開き、ターミナルとブラウザーの両方に同じ短いコードを表示して、承認を待ちます。オプションの keyring パッケージがインストールされ、正常に動作している場合は、認証情報を OS のキーリングに保存します。それ以外の場合は、プライベートなディレクトリーおよびファイル権限を設定した ~/.config/mainbook/credentials.json に保存します。ページクレジットを消費せずに、サーバー側で有効な認証情報を確認するには mainbook-mcp auth status を実行してください。mainbook-mcp auth logout は、まず保存済みのキーを無効化してからローカルのコピーを削除します。MainBook に接続できない場合は、そのキーが引き続き有効である可能性を明確に伝えます。再度サインインすると、置き換え後の認証情報を保存する前に、以前保存されていたキーが無効化されます。デバイストークンのレスポンスにはメールアドレスもアカウント ID も含まれないため、ステータスでは推測せず、アカウント情報が提供されていないことを示します。

次に、クライアントの MCP 設定にエントリーを 1 つ追加します。Claude Desktop（Settings → Developer → Edit Config）、Claude Code、Cursor では同じブロックを使用でき、キーを設定にコピーする必要はありません。

{
  "mcpServers": {
    "mainbook": {
      "command": "uvx",
      "args": ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"]
    }
  }
}

Codex は TOML を読み込むため、同じ内容を ~/.codex/config.toml に記述します。

[mcp_servers.mainbook]
command = "uvx"
args = ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"]

uvx は uv に含まれています。brew install uv または curl -LsSf https://astral.sh/uv/install.sh | sh で一度インストールしてください。公開済みパッケージを取得して実行するため、手動でダウンロードする必要も、更新する必要もありません。uv を追加したくない場合は、pip install mainbook-mcp を実行し、同じ引数を指定して "command": "mainbook-mcp" を使用してください。その場合は、pip install -U mainbook-mcp でご自身でアップグレードします。

フォルダーの引数で指定した場所からのみ、サーバーは明細を読み込んだり、結果を書き込んだりできます。指定範囲外へのアクセスは拒否されます。MAINBOOK_ALLOWED_DIRS を使用すると、同じリストを環境変数で設定できます。区切りにはプラットフォームの os.pathsep（macOS/Linux では :、Windows では ;）が使われます。

スクリプトおよび CI 用の手動 API キー

MAINBOOK_API_KEY は、保存済みのログイン情報より優先されます。対話型ブラウザーを利用できない自動化では、手動の方法を使用してください。この環境変数によって新しく保存した認証情報が引き続き上書きされる場合、auth login が警告します。

export MAINBOOK_API_KEY="mb_live_REPLACE_ME"
mainbook-mcp

手動キーは https://mainbook.ai/developer で作成および無効化できます。キーをコミットしないでください。

設定ファイルを編集せずに使う Claude Desktop

Claude Desktop では、単一ファイルのバンドルも使用できます。Extensions → Install Extension… を選択し、 mainbook.mcpb を指定してください。ダイアログで API キーとフォルダーを求められます。また、独自の Python ランタイムを管理するため、事前のインストールは不要です。上記の設定ブロックでも同じことができますが、すでにほかのサーバーを設定ファイルで管理している場合はこちらが適しています。このディレクトリからバンドルをビルドするには、次を実行します。

npx --yes @anthropic-ai/[email protected] validate manifest.json
npx --yes @anthropic-ai/[email protected] pack . dist/mainbook.mcpb

提供する機能

• convert_bank_statement：ページ単位のクレジットを消費するジョブを作成し、PDF を 1 件アップロードして変換を開始します。最大 30～900 秒間ポーリングし、確認済みの結果を返します。JSON はそのまま返されます。ローカルの stdio モードでは、XLSX／CSV のデータはディスクに書き込まれ、完全なパスのみがモデルコンテキストに渡されます。
• get_conversion：タイムアウト後にジョブの状態を確認し、JSON をそのまま返すか、指定したローカルの保存先に XLSX／CSV を書き込みます。
• list_conversions：アカウントのジョブをカーソルページ 1 件分と、next_cursor を返します。
• get_balance：クレジットの合計、予約済み、利用可能な数を返します。いずれも PDF のページ数で表されます。
• output_folder：デフォルトのローカル結果フォルダーを読み取るか、変更します。

ローカルの stdio モードでは、5 つすべてのツールが表示されます。ホスト型 HTTP モードでは最初の 4 つだけが表示されます。サーバーのディスクはクライアントのものではないため、output_folder はリモートでは公開されません。

クレジットの購入、支払い、ジョブの削除、アカウントデータの変更を行うツールはありません。変換の作成、ローカル結果ファイルの書き込み、出力設定の変更が可能なツールは、読み取り専用ではないものとしてマークされています。get_conversion は、ファイルを書き込まないホスト型 HTTP では読み取り専用ですが、XLSX または CSV を書き込む可能性があるローカルの stdio では読み取り専用ではありません。既存の結果ファイルが置き換えられることはないため、破壊的なツールとしてマークされているものはありません。

結果ファイルの保存先

ローカルの stdio クライアント（Claude Desktop、Claude Code、Cursor、Codex）では、XLSX および CSV の結果は次の順序で、最初に利用可能な保存先に書き込まれます。

1. convert_bank_statement または get_conversion に渡された output_path（絶対パスのファイル名、または既存のフォルダー）。
2. output_folder に記憶されているフォルダー。
3. 元の PDF と同じ場所。同じベース名に結果の拡張子を付けて保存します。

get_conversion では、元の PDF のフォルダーを推測できません。output_path も有効な保存済みフォルダーも指定されていない場合、保存先を推測せず、明確なエラーを返します。ファイルに関する成功応答には、絶対パスと、どのルールで保存先が選択されたかが記載されます。既存のファイルが置き換えられることはありません。statement.xlsx が存在する場合は、statement (2).xlsx、続いて (3) のように保存されます。

クライアントに引数なしで output_folder を呼び出すよう依頼すると、現在の設定と許可されているすべてのフォルダーを確認できます。許可されている絶対パスのディレクトリを指定して設定するか、next_to_source を渡してデフォルトに戻します。この設定は、同じマシン上のローカルクライアント間で ~/.mainbook/preferences.json に共有されます。保存先のフォルダーが存在しない、または許可されなくなった場合は無視され、そのフォールバックが結果に記載されます。

JSON は引き続きそのまま返されます。明示的な output_path が指定された場合に限り、.json ファイルにも書き込まれます。リモート HTTP モードでは、サーバーのディスクはクライアントのものではないため、ローカルパスと output_folder は利用できません。XLSX／CSV は、OAuth でサインインした場合は 10 分で期限切れになる一度限りのダウンロードリンクとして返され、従来の mb_live_ キーで認証した場合は REST ダウンロード手順として返されます。

手動での要件とインストール

• Python 3.11 以降
• MainBook アカウント

このディレクトリから：

python3 -m venv .venv
.venv/bin/python -m pip install .

プライベートな JSON フォールバックより OS キーリングを優先するには、ログインコマンドまたはローカルサーバーを実行するすべての環境に、オプションの追加機能をインストールしてください。

.venv/bin/python -m pip install '.[keyring]'

pip install -e . ではなく、通常のインストールを使用してください。このチェックアウトでは、編集可能インストールによって .pth ファイルが書き込まれますが、インタープリターがそれを読み込まないため、パッケージがインストール済みに見えるにもかかわらず、python -m mainbook_mcp は "No module named mainbook_mcp" というエラーで失敗します。同一の内容を別の名前のファイルにすると認識されるため、内容は問題なく、原因は依然として不明です。通常のインストールなら、この問題を完全に回避できます。

自動化に手動の方法を使用する場合は、mb_live_... の値をシークレット用の環境またはクライアント設定に保存してください。決してコミットしないでください。

Streamable HTTP モード

MainBook がこのサーバーを https://mcp.mainbook.ai/mcp で実行するため、リモート MCP に対応するクライアントには何もインストールする必要がありません。この URL を claude.ai、Claude Desktop、ChatGPT、または Cursor に貼り付け、クライアントから求められたら MainBook アカウントでサインインしてください。キーを設定にコピーする必要はありません。Cursor は自身を登録する代わりに固定のクライアント ID を使用するため、次のブロックを渡してください。

{
  "mcpServers": {
    "mainbook": {
      "url": "https://mcp.mainbook.ai/mcp",
      "auth": {
        "CLIENT_ID": "mainbook-cursor",
        "scopes": ["mainbook:read", "mainbook:convert"]
      }
    }
  }
}

サインインできないクライアントでも、mainbook.ai/developer から取得したレガシーキーを送信できます。

Authorization: Bearer mb_live_REPLACE_ME

どちらの認証情報も各リクエストから読み取られるため、クライアントを使うユーザーはそれぞれ自分の MainBook アカウントに接続し、自分のページクレジットを使用します。initialize と tools/list は認証情報なしで応答しますが、各ツール呼び出しには認証情報が必要です。HTTP 経由ではローカルのファイルパスと output_folder は使用できません。サーバーのディスクは自分のものではないため、file_path の代わりに file_url を渡してください。XLSX または CSV の結果は、OAuth セッションでは一度限りのダウンロードリンク（10 分間有効、1 回限りの使用）として返され、レガシーの mb_live_ キーでは REST ダウンロードの指示として返されます。

同じリモートモードを自分で実行することもできます。これは JSON 応答を返すステートレスな Streamable HTTP です。

mainbook-mcp --transport http --host 127.0.0.1 --port 8000

MCP エンドポイントは http://127.0.0.1:8000/mcp になります。各クライアントはそれぞれ独自のヘッダーを送信してください。

Authorization: Bearer mb_live_REPLACE_ME

ヘッダーは各ツール呼び出しリクエストから読み取られ、グローバル状態には保存されません。ホスト型 HTTP モードでは、MAINBOOK_API_KEY、OS キーリング、ローカルの認証情報ファイルは参照されません。Codex リモートモードの場合：

[mcp_servers.mainbook]
url = "https://mcp.mainbook.ai/mcp"
bearer_token_env_var = "MAINBOOK_API_KEY"
tool_timeout_sec = 920
default_tools_approval_mode = "writes"

自分でデプロイする場合は、URL を独自のホストに置き換えてください。セルフホスト可能なデプロイでも、通常の HTTPS 終端処理とアクセス制御が必要です。

ホスト型サービスでの OAuth

アカウントへのサインインは https://mcp.mainbook.ai/mcp で利用できます（2026-08-20 より）。このソースツリーでは検証機能がデフォルトで無効になっているため、自分で実行するデプロイでは意図的に有効化する必要があります。有効化されている場合も、initialize と tools/list は引き続き公開され、各ツール呼び出しでは既存の mb_live_ キーまたは MainBook RS256 アクセストークンのいずれかを使用できます。OAuth トークンは、設定された MainBook JWKS URL のみを使用してローカルで検証され、Developer API に転送されることはありません。MCP サーバーは、内部の REST リクエストごとに有効期間 60 秒の新しい X-MainBook-Service 認証情報を送信します。

ホスト型ツールのスコープは単一のマップで固定されています。convert_bank_statement には mainbook:convert が必要です。get_balance、get_conversion、list_conversions には mainbook:read が必要です。保護対象リソースのメタデータは、フラグが有効な場合にのみ /.well-known/oauth-protected-resource/mcp で公開されます。

環境変数

• MAINBOOK_API_KEY：stdio では任意で、保存済みのログイン情報より優先されます。HTTP モードでは無視されます。HTTP モードでは、各ツール呼び出しに独自の Bearer ヘッダーを付ける必要があります。
• MAINBOOK_API_BASE_URL：REST ホスト。デフォルトは https://api.mainbook.ai です。サーバーは /api/v1/developer を追加します。
• MAINBOOK_ALLOWED_DIRS：ソースの読み取りと結果の書き込みを許可するローカルフォルダー。プラットフォームの os.pathsep（macOS/Linux では :、Windows では ;）で区切ります。位置引数で指定したフォルダーが優先されます。どちらも指定されていない場合、デフォルトは ~/Downloads、~/Desktop、~/Documents です。
• MAINBOOK_MCP_TRANSPORT：stdio（デフォルト）または http。
• MAINBOOK_MCP_HOST：HTTP バインドホスト。デフォルトは 127.0.0.1 です。
• MAINBOOK_MCP_PORT：HTTP バインドポート。デフォルトは 8000 です。
• MAINBOOK_MCP_OAUTH_ENABLED：ホスト型 OAuth 検証機能のフラグ。デフォルトは false です。このフラグがオフの場合、メタデータはなく、ホスト型 Bearer の処理では従来の mb_live_ の動作が維持されます。
• MAINBOOK_MCP_OAUTH_ISSUER：信頼する発行者の完全一致値。デフォルトは https://api.mainbook.ai です。
• MAINBOOK_MCP_OAUTH_JWKS_URL：信頼する JWKS URL。デフォルトは https://api.mainbook.ai/.well-known/jwks.json です。トークンヘッダーの URL は無視されます。
• MAINBOOK_MCP_OAUTH_RESOURCE：オーディエンス／リソースの完全一致値。デフォルトは https://mcp.mainbook.ai/mcp です。
• MAINBOOK_MCP_OAUTH_CLOCK_SKEW_SECONDS：NumericDate のクロック許容差。デフォルトは 5 です。
• MAINBOOK_MCP_OAUTH_MAX_TOKEN_AGE_SECONDS：iat からの許容最大経過時間。デフォルトは 600 です。
• MAINBOOK_MCP_OAUTH_JWKS_CACHE_TTL_SECONDS：JWKS キャッシュの有効期間。デフォルトは 300 です。
• MAINBOOK_MCP_OAUTH_JWKS_REFRESH_MIN_INTERVAL_SECONDS：不明な kid の更新を試みる最小間隔。デフォルトは 30 です。
• MCP_SERVICE_SIGNING_SECRETS：カンマ区切りのサービスドア用シークレット。MCP は先頭の値で署名します。ローテーション中は、Django は現在の値と以前の値を受け入れることができます。OAuth が有効な場合は必須です。絶対にコミットしないでください。

ファイルとネットワークの安全性

• file_path と file_url は同時に指定できません。file_path が受け付けられるのはローカルの stdio 経由のみです。HTTP モードではファイルシステムローダーの実行前に拒否され、file_url が必要です。
• ローカルの file_path へのアクセスと結果ファイルの書き込みには、同じ設定済みフォルダーを使用します。位置引数で指定した CLI ディレクトリーは MAINBOOK_ALLOWED_DIRS より優先されます。また、環境変数の設定は、デフォルトの ~/Downloads、~/Desktop、~/Documents より優先されます。各ルートは展開および解決され、存在しない ルートは無視されます。サーバーの起動時には、有効なルートが stderr に出力されます。ルートが 1 つも残らない場合、ローカルアクセスは安全側に倒して拒否されますが、サーバーは引き続き実行されます。
• 出力先の親ディレクトリーは書き込み前に解決され、ディレクトリーの同一性を確認します。これにより、シンボリックリンクによって結果が許可されたフォルダー外に リダイレクトされることを防ぎます。結果ファイルは排他的かつ衝突しない方法で作成され、 既存のファイルは上書きされません。
• ~/.mainbook/preferences.json はアトミックに置き換えられます。.mainbook ディレクトリーのモードは 0700、 設定ファイルのモードは 0600 です。不正な形式または読み取り不能な設定は安全に無視されます。
• 端末の認証情報には、オプションパッケージが使用可能な場合、OS のキーチェーンを使用します。フォールバックとして使用する ~/.config/mainbook/credentials.json は、モード 0700 のディレクトリー内でアトミックに置き換えられ、 モードは 0600 です。最上位の項目は API のベース URL をキーとして保存されます。
• ローカルパスは許可リストの確認前に展開され、厳密に解決されます。そのため、.. やシンボリックリンクを使って、許可されたフォルダー外の対象を フォルダー内にあるように見せることはできません。解決後のパスはルートそのものではなく、 ルートの配下に厳密に含まれている必要があります。
• ローカルファイルは一度だけ開きます。サーバーはそのファイル記述子に対して fstat を使用し、通常のファイルであることを確認して 50 MiB の上限を適用した後、 同じファイル記述子を使って上限付きで読み込みます。これにより、確認と読み込みの間にファイルが置き換えられる時間的な隙間は解消されますが、 パスの解決からファイルを開くまでの競合状態を完全に排除するものではありません。その間にパスが置き換えられる可能性は 依然としてあります。
• pypdf を呼び出す前に、ローカルファイルの先頭 1024 バイト以内に %PDF- が含まれている必要があります。ファイル名の 拡張子を使って PDF かどうかを判断することはありません。
• リモートファイルには HTTPS を使用する必要があります。リダイレクトは追跡されません。
• IPv4 と IPv6 のいずれについても、いずれかのアドレスがプライベート、ループバック、リンクローカル、メタデータ用、予約済み、 またはその他の非パブリックなアドレスである DNS の応答は拒否されます。
• URL のダウンロードでは、検証済みの数値 IP アドレスに接続しながら、TLS 証明書の検証と HTTP の Host ヘッダーには元のホスト名を使用し、 DNS リバインディングの競合状態を防ぎます。
• Content-Length と実際にストリーミングされたバイト数には、それぞれ独立して 50 MiB の上限が適用されます。
• PDF は pypdf を使ってローカルで解析され、ページ数は 500 ページまでに制限されます。
• MainBook からの署名付きアップロード用ヘッダーは変更せずに転送されます。MainBook の Bearer キーがストレージに送信されることはありません。

開発時のチェック

.venv/bin/python -m pip install '.[dev]'
.venv/bin/pytest
.venv/bin/pytest --cov=mainbook_mcp --cov-report=term-missing --cov-report=annotate:cov_annotate
.venv/bin/ruff check .

すべての REST テストではモックまたはローカルのスタブを使用します。実際の MainBook API キーを必要とするテストや、受け付けるテストはありません。