mercury-multiorg-mcp について
mercury-multiorg-mcpは、複数のMercury組織に1つのAIセッションからアクセスする非公式の読み取り専用MCPサーバーです。明示的なエンティティキーで呼び出しを振り分け、構造化データの返却項目を許可リストで制限します。
主な機能
- 011つのセッションで複数組織にアクセス
- 02呼び出しごとにエンティティを明示
- 03Mercury APIへの読み取り専用アクセス
- 04構造化結果の項目を許可リストで制限
- 05明細書と請求書PDFの取得は任意
活用シーン
- 01複数のMercury組織のデータを確認
- 02エンティティ別に口座や取引情報を取得
- 03原本が必要なセッションでPDF取得を有効化
MCP 対応
ローカルstdioのMCPツールを通じてMercury組織のデータを提供します。文書アクセスを明示的に有効にした場合のみ、PDFツールが登録されます。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
uvx mercury-multiorg-mcpMERCURY_TOKEN_ACME_MAINシークレットExample only. Each organization needs one read-only Mercury API token in the environment variable named by its token_env in your registry. Names are yours to choose but must match MERCURY_TOKEN_[A-Z0-9_]+ (for example MERCURY_TOKEN_<ENTITY_KEY>); set one per organization and rename this example to match.MERCURY_ENTITIES_FILEAlternative to --entities: path to the entity registry YAML. Ignored when --entities is passed.MERCURY_API_BASEMercury API host. Allowed without extra flags: https://api.mercury.com, https://api-sandbox.mercury.com (with sandbox tokens), or a loopback mock.MERCURY_ALLOW_DOCUMENTSSet to true to register get_statement_pdf and get_invoice_pdf, which return statement and invoice PDFs unredacted. Off by default.ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。
ツール
ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。
詳細
mercury-multiorg-mcp
非公式です。Mercury との提携や承認を受けていません。
読み取り専用のMCPサーバーで、1つのAIセッションから複数のMercury組織にアクセスできます。Mercury APIトークンは1つの組織内から作成するため、このサーバーは組織ごとに1つの読み取り専用トークンを保持し、明示的なentityキーに基づいてすべてのツール呼び出しを振り分けます。
バージョン0.1.6（CHANGELOG.mdを参照）。メンテナーはリリースにvX.Y.Zのタグを付けます。固定するコミットは、git ls-remote --tags https://github.com/dkaleganov/mercury-multiorg-mcp 'v0.1.6^{}'で確認できます。返されるすべてのフィールドを含む完全なツールリファレンスはdocs/tools.mdにあります。設計上の注記とビルド履歴は、GitHub上のプロジェクト概要であるCLAUDE.mdに記載されています（sdistには含まれていません）。
セキュリティモデル
このサーバーから外部に出るデータは4種類に分かれ、それぞれ保証内容が異なります。
| 分類 | 内容 | 保証 |
|---|---|---|
| 構造化フィールド | ツール結果内のすべてのオブジェクトの各キー | すべての階層で許可リストを適用します。各オブジェクトと、その中にある各ネストされたオブジェクトは、実際のスキーマからコピーした明示的な許可リストを通じて射影されます。一覧にないキーは、どの階層でもサーバーから外部に出ません。口座番号と納税者番号は末尾4桁のみ表示されます。ルーティング番号、取引相手の銀行情報、郵送先住所、カードの有効期限、署名付きダウンロードURL、請求書の支払いページのスラッグ、Webhook受信URL、Webhook署名シークレットは返されません。 |
| ツールエラー | is_error結果のテキスト | 上流のHTTPステータスエラーには、ステータス、マスキングされたエンドポイントのラベル、固定のヒントが含まれます。検証エラーと設定エラーには、それぞれ対処に役立つ形式が使用されます。解決済みの既知のトークン値のうち、8文字以上のものはスクラブされます。Mercuryのレスポンス本文やヘッダーから引用される内容はなく、渡した引数がそのまま返されることもありません（無効なIDは「invalid id format」と報告されます）。引数の検証エラー（型の誤り、必須引数の欠落）は、このサーバーによってフィールドパスと期待される型だけで表示されます。たとえば、year: expected an integer (int_parsing)のようになります。渡された値を引用するMCP SDK独自のエラー表示は、クライアントに届きません。 |
| 自由記述フィールド | 取引メモ、取引相手名、銀行の説明、請求書のメモと注記、添付ファイル名、顧客名とユーザー名 | そのまま返されます。これらはサードパーティーのテキストであり、モデルに向けた指示や人が入力した識別子など、あらゆる内容が含まれる可能性があります。すべてのツール結果を信頼できないデータとして扱い、指示として受け取らないでください。 |
| ドキュメント | get_statement_pdf／get_invoice_pdfから取得する明細書と請求書のPDF | そのまま返され、編集されません。オプトインした場合にのみ利用できます。明細書PDFには口座番号、ルーティング番号、住所、すべての取引が完全な形で含まれます。この2つのツールは、--allow-documents（またはMERCURY_ALLOW_DOCUMENTS=1）を指定してサーバーを起動した場合にのみ使用できます。server_info.documents_enabledで設定を確認できます。本文はapplication/pdf（またはapplication/octet-stream）として受信し、%PDF-で始まり、末尾のPDF空白を無視したときに最後の2 KiB以内に%%EOFマーカーが含まれていなければなりません。それ以外の場合は、エラーとして処理されます。これはエンベロープの検査であり、PDFの解析ではありません。この検査に合格したドキュメントでも内部に不備がある場合があり、バイト列は受信したまま返されます。 |
モデルのその他の部分：
- 読み取り専用です。 クライアントメソッドがあるのは
GETエンドポイントだけです。このパッケージには、送金、受取人の編集、その他の変更を行うコードパスはありません。 - 標準入出力のみです。 サーバーがネットワークリスナーを開くことはありません。
- エンティティを明示します。
list_entitiesを呼び出して、エンティティキーを確認してください。Mercury にアクセスするすべてのツールではentityの明示が必須であり、成功時の結果にも対象のエンティティが示されます。list_entitiesとserver_infoにはエンティティ引数は不要です。デフォルトのエンティティはありません。 - トークンは環境変数内にとどまります。 レジストリでは、組織ごとに環境変数を指定します（変数名は
MERCURY_TOKEN_…でなければならないため、レジストリからサーバーを別のシークレットに向けることはできません）。サーバーが読み取るのはその環境変数だけです。エラーやログに含まれるトークンは、末尾 4 文字までです。既知のトークンの値そのものを対象としたスクラビングは、8 文字以上の値に適用されます。設定値がそれより短い場合、値そのもののスクラビングは行われません（secret-token:形式とAuthorizationヘッダーに対するスクラビングは引き続き適用されます。また、そもそもメッセージに上流や呼び出し元のデータが引用されることはありません）。起動時、設定値に Mercury が文書化しているsecret-token:プレフィックスがない場合、サーバーはエンティティごとに警告します。 - Mercury のホストのみです。
--api-base／MERCURY_API_BASEに指定できるのは、https://api.mercury.com、https://api-sandbox.mercury.com、またはループバックのモックです。コマンドラインで--allow-custom-api-baseを渡した場合はこの限りではありません。継承された環境変数だけでベアラートークンの送信先が別のホストに変わることはありません。 - 通信データのバイト数を制限します。 すべてのリクエストで圧縮を拒否します（
Accept-Encoding: identity）。JSON／PDF の読み取りでは、読み取りを開始する前に identity 以外のエンコーディングを拒否します。Keepalive では本文を未読のまま接続を閉じます。上限は PDF が 10 MiB（10,485,760 バイト）、JSON が 32 MiB（33,554,432 バイト）で、ストリーミング中に実際に受信したバイト数に対して適用されます。小さく圧縮された本文が、メモリ上で上限を超えて展開されることはありません。エラーレスポンスは一切読み取りません。 - 完全に処理するか、明確に失敗します。 ページの走査は、指定された上限または API の終端で停止します。
pageオブジェクトが欠落しているか不正な場合は失敗します。終端のnextPageは省略または null が許容されます。完全に重複する ID は除外され、その件数が記録されます。内容が異なる場合は失敗します。さらにデータがあると通知されているのに、新たに使用可能な行がないページは失敗します。200 ページを超える走査が必要な場合は失敗し、財務データのcursorが負でない整数でない場合も失敗します。重複件数は、ページネーションを伴うすべての結果のduplicates_droppedと、reportable_totals.totalsに報告されます。そのため、停止した走査、不正な走査、または二重計上された走査に基づいて合計が作成されることはありません。 - 期間指定のフィードは全件走査します。 Mercury はイベントや財務データの取引についてソートキーを文書化していません。そのため、クライアント側で期間を指定する場合（
list_eventsのsince、list_treasury_transactionsのstart／end）、上限のあるフィード全体（イベントは 90 日分、財務データの台帳は最大 200 ページ）を走査し、ここでフィルタリングして新しい順に並べ替えてからlimitを適用します。truncatedは正確です。処理コストは指定期間ではなく、フィードの量に比例します。 - バイナリ文書はメモリ内に保持します。 PDF は埋め込みの
application/pdfブロブ（base64）として返され、ディスクには書き込まれません。 - パス ID を検証します。 リクエストパスの一部となるすべての ID は、安全な単一セグメントでなければなりません。呼び出し先が別のエンドポイントに切り替わることはありません。
- 起動時のエラーは 1 行で、終了コードは 2 です。 レジストリの欠落や形式不正（文字列以外の YAML キーを含む）、ファイルの読み取り不可、不正な
--env-file、または許可されていない API ホストの場合、標準エラー出力に 1 行を表示して、終了ステータス 2 で終了します。秘匿情報をマスキングする例外フックは、何かを読み込む前にインストールされるため、起動時にマスキングされていないトレースバックが出力されることはありません。 - 申告処理は一切行いません。
reportable_totalsは申告前の照合用です。Mercury に 1099 の申告エンドポイントはありません。申告は各組織のダッシュボードで行います。 衛生管理。 このパッケージは公開リポジトリにあります。追跡対象のファイル、フィクスチャ、コミットメッセージには、トークン、口座番号、金融識別情報は含まれていません。ただし、意図的な例外が2つあります。1つ目は、パッケージのauthorsメタデータにメンテナー本人の名前が記載されていることです（リポジトリ所有者の承認済み）。それ以外の人の業務上・個人上の名前は記載されていません。2つ目は、履歴に関する注記です。Phase 1 の最初のコミットでは、フィクスチャのサンプルデータに実在する公開 ABA ルーティング番号を使用していました。次のコミットで明らかに偽の値に置き換えたため、すべてのタグ付きファイルツリーには含まれていませんが、祖先コミットには残っています。この番号が特定するのは銀行であり、口座ではありません。また、履歴は意図的に書き換えていません。このリリースでは、履歴全体を対象とした gitleaks スキャンに合格しました。
リポジトリの履歴。 このパッケージは、v0.1.3 まで複数プロジェクトのモノレポで開発され、履歴を保持したまま v0.1.4 でこのリポジトリに移行しました（同じコミットをこのリポジトリの構成に合わせて書き換えているため、SHA は元のものと異なります）。0.1.3 までのリリースは、元のリポジトリでは mercury-v0.1.x としてタグ付けされており、こちらでは v0.1.x としてタグ付けされています。今後のリリースタグは vX.Y.Z 形式です。上記の衛生管理に関する2つの例外は、どちらもこの履歴にそのまま当てはまります。
インストール
PyPI から、固定したリリースを uvx で実行します（クローンは不要です）。
uvx [email protected] --entities /private/path/entities.yaml
uvx <package>@<version> は、隔離されたキャッシュ環境で指定したリリースを正確に実行します。pip install 'mercury-multiorg-mcp==0.1.6' も使用できます。この場合、mercury-multiorg-mcp と mercury-multiorg-mcp-keepalive が PATH に追加されます。
Python 3.11 以降と、uv（uvx 用）が必要です。
ソースから／コミットを固定してインストール
クローンから実行します。
git clone https://github.com/dkaleganov/mercury-multiorg-mcp.git # or [email protected]:dkaleganov/mercury-multiorg-mcp.git
cd mercury-multiorg-mcp
uv sync
uv run mercury-multiorg-mcp --entities /private/path/entities.yaml
または、uvx で完全なコミット SHA を固定します（タグではなく SHA を固定してください。完全な SHA は不変でキャッシュにも安全ですが、タグは移動する可能性があります）。
uvx --from 'git+https://github.com/dkaleganov/mercury-multiorg-mcp@<FULL_COMMIT_SHA>' \
mercury-multiorg-mcp --entities /private/path/entities.yaml
設定
- 各 Mercury 組織で、組織切り替えメニュー → All Settings → Tokens の順に開き、読み取り専用トークンを作成します（IP 許可リストは不要です）。
entities.example.yamlをこのリポジトリの外にあるプライベートな場所にコピーし、組織を一覧にします（key、display_name、token_envを指定します。環境変数名はMERCURY_TOKEN_で始まる必要があります）。- サーバーの起動環境で、レジストリに記載された名前を使って、組織ごとに環境変数を1つずつエクスポートします（名前は
.env.exampleを参照してください）。設定の読み込み元はプロセス環境変数のみです。--env-file <path>を指定しない限り、.envファイルは読み込まれません。そのため、リポジトリ、ホームディレクトリ、uvxキャッシュから誤って設定が読み込まれることはありません。 - 任意：サンドボックスで作成したトークンを使う場合は、
MERCURY_API_BASE=https://api-sandbox.mercury.comを設定します。 - 任意：PDF ツール2つを登録するには、
--allow-documents（またはMERCURY_ALLOW_DOCUMENTS=1）を指定します。セッションで未編集のドキュメントが本当に必要な場合を除き、無効のままにしてください。
コマンドライン
| フラグ／環境変数 | 意味 |
|---|---|
--entities PATH / MERCURY_ENTITIES_FILE | エンティティレジストリの YAML です。必須です（フラグが環境変数より優先されます）。暗黙のデフォルト値はありません。 |
--env-file PATH | トークンを解決する前に、この dotenv ファイルを読み込みます。既存の環境変数が優先されます。このフラグを指定しない場合、どこからも dotenv ファイルは読み込まれません。 |
--api-base URL / MERCURY_API_BASE | Mercury API のホストです。デフォルトは https://api.mercury.com です。使用できるのは、本番環境、https://api-sandbox.mercury.com、またはモック用の localhost／127.0.0.1 上のプレーンな http:// です。 |
--allow-custom-api-base | ほかの任意の https:// ホストを許可します。環境変数からは絶対に設定しないでください。カスタムホストの使用を、常に意図的なコマンドラインでの選択とするためのものです。 |
--allow-documents / MERCURY_ALLOW_DOCUMENTS=1 | get_statement_pdf と get_invoice_pdf を登録します（ドキュメントは編集されずに返されます）。デフォルトでは無効です。有効にしない場合は 24 個、有効にすると 26 個のツールが利用できます。 |
--version | パッケージのバージョンを表示して終了します。 |
起動時に問題（レジストリの欠落または形式の不正、無効な YAML、読み取り不能な ファイル、不正な API ベース）があると、stderr に 1 行を出力し、ステータス 2 で 終了します。stdout は MCP プロトコル専用です。
Mercury は、API トークンが 45 日間使われないと（トークンの
非アクティブ期間のカウント）、そのトークンを削除します。また、45 日間使用されていない権限は
別途ダウングレードされます。非アクティブ期間のカウントが
期限切れにならないよう、mercury-multiorg-mcp-keepalive を定期的に実行してください。cron と
launchd の設定例については、docs/keepalive.md を参照してください。
ローカルの stdio MCP クライアントで使用できます
ローカル stdio サーバーと、ネゴシエーションされたプロトコルバージョンをサポートする MCP クライアントに 対応しています。プライベートレジストリと環境ファイルにアクセスできる クライアントホストで、次のコマンドを設定してください。ドキュメントの 表示方法とクライアントの承認ポリシーはクライアントによって異なります。このサーバーは HTTP も SSE も公開しません。コマンドと引数は、すべてのクライアントで同じです。
command: uvx
args: [email protected] --entities /private/path/entities.yaml
optional extra arg: --allow-documents (registers the two unredacted PDF tools)
PyPI リリースではなく、固定したコミットを実行するには、最初の引数を
--from、git+https://github.com/dkaleganov/mercury-multiorg-mcp@<FULL_COMMIT_SHA>、mercury-multiorg-mcp
に置き換えてください（「ソースから実行／固定コミット」を参照）。
トークンは、レジストリに指定された名前の環境変数としてサーバーに渡されます。
トークンを渡す方法は 2 つあります。クライアントの設定にある env ブロックを使う方法（クライアントが
シェルから ${MERCURY_TOKEN_ACME_MAIN} などのプレースホルダーを展開する場合に限ります。
設定ファイル内のトークンを直接記述すると、ディスク上に秘密情報が保存されます）、または
プライベート dotenv ファイルを使う方法です。--env-file /private/path/mercury.env で
プライベート dotenv ファイルを指定すると、クライアント固有のプレースホルダー展開を避けられます。
クライアントホストからそのファイルを読み取れる必要があります。既存のプロセス環境変数が優先されます。レジストリと dotenv ファイルは、すべての
リポジトリの外に置き、自分のユーザーのみが読み取れるようにしてください。
Claude Code（.mcp.json）
Claude Code は、環境変数から ${VAR} を展開します。このリポジトリには
.mcp.json の例が含まれています。この形式を検出するクライアントでは、
起動を提案される場合があります。この設定は合成例のレジストリを参照しており、
認証情報は含まれていません（そのため、list_accounts はエンティティごとに適切なエラーを返します）。
{
"mcpServers": {
"mercury-multiorg": {
"command": "uvx",
"args": [
"[email protected]",
"--entities",
"/private/path/entities.yaml"
],
"env": {
"MERCURY_TOKEN_ACME_MAIN": "${MERCURY_TOKEN_ACME_MAIN}"
}
}
}
}
Claude Desktop（claude_desktop_config.json）
「設定」→「開発者」→「設定を編集」を開きます。この設定が
クライアント固有のプレースホルダー展開に依存しないよう、--env-file を使用してください。
{
"mcpServers": {
"mercury-multiorg": {
"command": "uvx",
"args": [
"[email protected]",
"--entities",
"/private/path/entities.yaml",
"--env-file",
"/private/path/mercury.env"
]
}
}
}
Codex CLI（~/.codex/config.toml）
[mcp_servers.mercury-multiorg]
command = "uvx"
args = [
"[email protected]",
"--entities", "/private/path/entities.yaml",
"--env-file", "/private/path/mercury.env",
]
# `env = { MERCURY_TOKEN_ACME_MAIN = "..." }` is also accepted, but values there are
# literal, so prefer --env-file over putting a token in this file.
Cursor／Windsurf のレガシー Cascade（mcp.json）
Cursor は .cursor/mcp.json または ~/.cursor/mcp.json を使用します。Windsurf のレガシー
Cascade は ~/.codeium/windsurf/mcp_config.json を使用します。現在のデフォルトである
Devin Local エージェントは独自の CLI 設定を使用します。この例は
レガシー Cascade を対象としています。どちらも mcpServers マップを使用します。クライアントの
ドキュメントに環境変数プレースホルダーを展開すると記載されていない限り、--env-file を使用してください。
{
"mcpServers": {
"mercury-multiorg": {
"command": "uvx",
"args": [
"[email protected]",
"--entities",
"/private/path/entities.yaml",
"--env-file",
"/private/path/mercury.env"
]
}
}
}
VS Code（.vscode/mcp.json）
VS Code は mcpServers ではなく servers マップを使用し、明示的に
"type": "stdio" を指定します。
{
"servers": {
"mercury-multiorg": {
"type": "stdio",
"command": "uvx",
"args": [
"[email protected]",
"--entities", "/private/path/entities.yaml",
"--env-file", "/private/path/mercury.env"
]
}
}
}
Gemini CLI（~/.gemini/settings.json または .gemini/settings.json）
{
"mcpServers": {
"mercury-multiorg": {
"command": "uvx",
"args": [
"[email protected]",
"--entities",
"/private/path/entities.yaml",
"--env-file",
"/private/path/mercury.env"
]
}
}
}
その他の stdio クライアント
ローカル stdio サーバーとネゴシエートされたプロトコルバージョンに対応し、プライベートレジストリと環境ファイルを読み取れるホストで動作するクライアントであれば、同じ uvx コマンドと引数を指定してください。サーバーはネットワークリスナーを開かないため、HTTP または SSE トランスポートは提供されません。
ツール
Mercury にアクセスするすべてのツールでは、明示的な entity が必要で、成功時の結果にその値が含まれます。list_entities と server_info では entity 引数は不要です。limit 引数を持つ 7 つのツールは count と truncated を返します。全件を返すツールには公開された上限はありません。ページ分割された結果には、重複に関する診断情報（duplicates_dropped：走査時に除外された同一行）も含まれます。フィールドごとの詳細なリファレンス：
docs/tools.md。
| ツール | 引数 | 戻り値 |
|---|---|---|
list_entities | — | エンティティキー、表示名、各トークンの環境変数が設定されているかどうか |
server_info | — | パッケージのバージョン、API のベース URL、エンティティ数、documents_enabled（シークレットは含みません） |
list_accounts | entity | 残高とaccountNumberLast4を含む口座 |
list_transactions | entity、account_id?、start?、end?、search?、limit=100 | Mercury API のdesc順の取引、truncatedフラグ |
reportable_totals | entity、year、threshold?（2025年まではデフォルトで600、2026年からは2000。従業員以外へのサービス提供および特定のMISC支払いが対象。有効な値は最大1,000,000,000） | 受取人ごとの1099照合用合計、needs_reviewの区分、unclassified、excluded_summary |
list_recipients | entity | 受取人：ID、名前、ニックネーム、ステータス、デフォルトの支払い方法、最終支払日、メールアドレス、isBusiness |
list_tax_docs | entity | 受取人ごとの税務フォーム添付ファイル、およびrecipients_without_docs |
get_org | entity | ID、正式名称、DBA、種別、サブスクリプションプラン、請求頻度、einLast4 |
list_statements | entity、account_id、start?、end?、limit=100 | Mercury API のdesc順の明細書メタデータ（マスキングされた口座番号とEIN、transactionCount） |
get_statement_pdf（オプトイン） | entity、statement_id | 埋め込みBlobとしての明細書PDF（≤ 10 MB）、未編集。--allow-documentsを指定した場合のみ |
list_treasury | entity | 残高と月次純利益を含むトレジャリー口座 |
list_treasury_transactions | entity、treasury_id、start?、end?、limit=100 | Mercury API のdesc順のトレジャリー台帳行。日付範囲を指定した場合は台帳全体を走査してフィルタリングし、canonicalDayの新しい順に並べ替えます |
list_treasury_statements | entity、treasury_id、document_type? | トレジャリーの明細書と税務書類（メタデータ） |
list_credit_accounts | entity | 残高を含むクレジット口座 |
list_cards | entity、account_id?、status?、limit=100 | カード：下4桁、名前、ニックネーム、種別、タイプ、ステータス、限度額、予算、ロック状態 |
get_card | entity、card_id | 1枚のカード。同じフィールドを含みます |
list_categories | entity | カスタム経費カテゴリ |
list_merchants | entity、search?、limit=100 | 優先加盟店（ID、名前） |
list_customers | entity | 売掛金の顧客：ID、名前、メールアドレス、deletedAt |
list_invoices | entity、status?、start?、end?、limit=100 | 売掛金の請求書（全件走査後、クライアント側でフィルタリング） |
get_invoice | entity、invoice_id | サービス期間と明細項目を含む1件の請求書 |
get_invoice_pdf（オプトイン） | entity、invoice_id | 埋め込みBlobとしての請求書PDF（≤ 10 MB）、未編集。--allow-documentsを指定した場合のみ |
list_invoice_attachments | entity、invoice_id | 添付ファイルのIDとファイル名（URLは含みません） |
list_users | entity | ユーザー：ID、名と姓、メールアドレス、ロール |
list_events | entity、since?、resource_type?、limit=100 | Mercury API のdesc順の変更イベント。sinceを指定した場合は90日分のフィード全体を走査してフィルタリングし、occurredAtの新しい順に並べ替えます。パッチはリソースごとの許可リストに基づいて再投影されます |
list_webhooks | entity | Webhook エンドポイント：ID、url_fingerprint、ステータス、enabled、イベントタイプ、フィルターパス（シークレットや受信先URLの一部は一切含みません） |
list_transactionsのstart／endはcreatedAt（YYYY-MM-DDまたは
ISO 8601）でフィルタリングします。MercuryのダッシュボードではpostedAtが表示される場合があるため、日付範囲はUIと異なることがあります。
フェーズ1および2のツールの戻り値
list_entities entities[] {entity, display_name, token_configured}
server_info name, version, api_base, entity_count, entities_with_token, transport, read_only,
documents_enabled
list_accounts entity, duplicates_dropped, accounts[] {id, name, nickname, legalBusinessName, kind, type,
status, availableBalance, currentBalance, createdAt, canReceiveTransactions,
dashboardLink, accountNumberLast4}
list_transactions entity, filters, count, truncated, duplicates_dropped, transactions[] {id, accountId,
amount, status, kind, createdAt, postedAt, estimatedDeliveryDate, failedAt,
reasonForFailure, counterpartyId, counterpartyName, counterpartyNickname,
bankDescription, externalMemo, note, mercuryCategory,
categoryData {id, name, visibleForCardSpend, visibleForOther, visibleForReimbursements} | null,
merchant {id, category, categoryCode, currency, amount}, checkNumber, cardId,
currencyExchangeInfo {convertedFromAmount, convertedFromCurrency, convertedToAmount,
convertedToCurrency, exchangeRate, feeAmount, feePercentage, feeTransactionId},
dashboardLink}
list_recipients entity, count, duplicates_dropped, recipients[] {id, name, nickname, status,
defaultPaymentMethod, dateLastPaid, emails [strings], contactEmail, isBusiness}
list_tax_docs see the `list_tax_docs` section below (documents[] {id, recipientId, recipientName,
fileName, formType, uploadedAt})
reportable_totals see the `reportable_totals` section below
フェーズ 3 のツールの戻り値
get_org entity, organization {id, legalBusinessName, dbas [{dbaName, dbaIsDefault}], kind,
subscriptionTier, billingCadence, einLast4}
list_statements entity, account_id, filters, count, truncated, duplicates_dropped,
statements[] {id, startDate, endDate, endingBalance, companyLegalName,
accountNumberLast4, einLast4, transactionCount}
get_statement_pdf content[0] text {entity, statement_id, mimeType, bytes, encoding, redacted: false};
content[1] embedded resource {uri, mimeType: application/pdf, blob (base64)}
list_treasury entity, count, duplicates_dropped, treasury_accounts[] {id, status, availableBalance, currentBalance,
createdAt, netReturns[] {month, netAmount, treasuryFee, status,
dividends[] {id, type, securityName, amount}}}
list_treasury_transactions entity, treasury_id, filters, count, truncated, duplicates_dropped, transactions[] {id, accountId, type,
amount, balance, canonicalDay, description, additionalDetails, security,
details {creditDescription, depositCounterpartyId, feeDescription,
manualAmendmentDescription, security, sweepDirection, tradeAction,
withdrawalCounterpartyId}}
list_treasury_statements entity, treasury_id, filters, count, duplicates_dropped, statements[] {id, accountId, documentType,
description, periodStart, periodEnd, creationDate, createdAt, updatedAt}
list_credit_accounts entity, count, credit_accounts[] {id, status, availableBalance, currentBalance, createdAt}
list_cards entity, filters, count, truncated, duplicates_dropped, cards[] {id, accountId, userId, nameOnCard, nickname,
lastFour, kind, type, status, physicalCardStatus, isAgentCard, spendLimitType,
spendLimit {amountCents, atmAmountCents, interval},
budgets[] {id, name, amountCents, remainingAmountCents}, merchantLock {id, name},
categoryLocks [strings], createdAt, updatedAt}
get_card entity, card {same fields as one list_cards row}
list_categories entity, count, duplicates_dropped, categories[] {id, name, visibleForCardSpend, visibleForOther,
visibleForReimbursements}
list_merchants entity, filters, count, truncated, duplicates_dropped, merchants[] {id, name}
list_customers entity, count, duplicates_dropped, customers[] {id, name, email, deletedAt}
list_invoices entity, filters, count, truncated, duplicates_dropped, invoices[] {id, invoiceNumber, status, amount,
currencyCode, customerId, destinationAccountId, invoiceDate, dueDate, createdAt,
updatedAt, canceledAt, poNumber, payerMemo, internalNote, ccEmails, achDebitEnabled,
creditCardEnabled, useRealAccountNumber}
get_invoice entity, invoice {list fields + servicePeriodStartDate, servicePeriodEndDate,
lineItems[] {name, quantity, unitPrice, salesTaxRate}}
get_invoice_pdf same two blocks as get_statement_pdf, keyed by invoice_id
list_invoice_attachments entity, invoice_id, count, attachments[] {id, fileName}
list_users entity, count, duplicates_dropped, users[] {userId, firstName, lastName, email, organizationRole}
list_events entity, filters, count, truncated, duplicates_dropped, events[] {id, resourceType,
resourceId, operationType, resourceVersion, occurredAt, changedPaths, mergePatch,
previousValues, patchOmitted?}
list_webhooks entity, count, duplicates_dropped, webhooks[] {id, url_fingerprint (first 8 hex chars of sha256 of the
receiver URL), status, enabled, eventTypes, filterPaths, createdAt, updatedAt}
上記のネストされた各オブジェクトには独自の許可リストがあり、Mercury が明日どの階層に追加するキーも、引き継がれずに除外されます。
リストは、トランザクション、明細書、財務トランザクション、イベントを除き、API のデフォルトの順序（文書化されていないソートキーによる昇順）を維持します。これらは Mercury API に desc 順でリクエストされます。Mercury はソートキーを文書化していないため、時系列（新しい順）が保証されるのはウィンドウ指定の呼び出しのみです。ウィンドウ指定の財務関連呼び出しは canonicalDay で、since を指定したイベントは occurredAt でソートしてから、limit が適用されます。ウィンドウを指定しない呼び出しでは、Mercury API の desc 順がそのまま返されます。truncated が true の場合、保持される行は、適用される順序の先頭部分です。
Mercury API に、文書化された引数（イベントの since、財務トランザクションと請求書の start／end、請求書の status）に対応するサーバー側フィルターがない場合、ツールはフィード全体を走査してここでフィルターを適用し、その旨を docs/tools.md に記載します。
reportable_totals
完了した資金移動（ステータスが sent）のうち、出金額があるものだけを集計し、UTC の postedAt（ダッシュボードに表示される可能性がある日付）に基づいて暦年に割り当てます。API の検索では、postedStart／postedEnd にそれぞれ1日の余裕を持たせます。年の範囲外の行はクライアント側で除外し、excluded_summary.outside_year に計上します。その年の全ページを順に取得します。取得を完了できない場合はエラーとし、部分的な合計は返しません。公開ドキュメントには取引の kind の意味が定義されていないため、この表では kind 名から判断できることだけを示しています。実際の組織での検証（2026年9月）では、金額が負の externalTransfer 行は、その組織自身のリンク済み外部口座および組織間送金でした。一方、実際にベンダーが開始した ACH 引き落としは kind other として届いていました。そのため、これら2つの kind は集計せず、人による確認対象とします。
| 判定 | Kinds | 備考 |
|---|---|---|
| 含める | outgoingPayment | 支払い詳細から取得した方法：ach、domesticWire、internationalWire、check、または unknown |
| 含める | exogenousWireDrawdown（金額が負） | 電信送金の引き落とし。相手方が開始したものと推定されます。ドキュメントには未記載（wireDrawdown） |
| 要確認 | externalTransfer（金額が負） | linked_account_transfers：通常は組織自身のリンク済み口座／外部口座、または組織間送金です。ベンダーが開始した ACH 引き落としが該当する場合もあります |
| 要確認 | other（金額が負） | unlabeled_debits：方法を示す情報がありません。通常はベンダーが開始した ACH 引き落とし、または Mercury の製品への支払いです |
| 除外 | internalTransfer、treasuryTransfer | 組織自身の口座 |
| 除外 | creditCardTransaction、debitCardTransaction、creditCardCredit、debitCardCredit | 1099-K はカード処理業者が提出します |
| 除外 | wireFee、personalBankingSubscriptionFee、billingEngineSubscriptionFee、cardInternationalTransactionFee* | 銀行手数料およびリベート |
| 除外 | incomingDomesticWire、incomingInternationalWire、checkDeposit、interestPayment | 入金 |
| 除外 | currencyCloudReturn | 返金された国際電信送金。元の取引はすでに集計されている可能性があるため、手動で差し引いてください |
| 除外 | expenseReimbursement | 従業員への経費精算 |
| 除外 | 集計対象、要確認、または未分類の kind のうち、ステータスが sent ではないもの、または金額が0以上のもの | not_settled:<status>／incoming |
| 未分類 | 表にない kind、または金額が欠落しているもの | 理由を添えて1件ずつ記載 |
受取人は counterpartyId でグループ化します（GET /recipients の受取人と一致する場合は確度 high、それ以外は medium）。ID がない場合は、取引相手名でグループ化します（low）。正規化した名前が同じ ID グループは相互参照され、受取人が複数の ID に分かれている場合に確認できるようにします。デフォルトの基準額は課税年度に応じて変わります。2025年の課税年度までは600、2026年以降は2000（2027年以降はインフレ調整）。これは、従業員以外へのサービスの対価および特定の MISC 支払いに適用されるデフォルト値です。該当するカテゴリ／年度の基準額を指定してください（IRS の Forms 1099-MISC および 1099-NEC の説明を参照）。解決された値は応答に含まれます。基準額は有限数で、0以上1,000,000,000以下である必要があります。それ以外の場合はエラーとなり、暗黙的に0として扱われることはありません。リアルタイム決済は、API がルーティング情報を返すかどうかに応じて、ach または unknown として表示されます。
戻り値：
entity, year, threshold resolved threshold (default depends on year)
date_basis {field: "postedAt", timezone: "UTC",
fallback_to_createdAt_count, api_filter: {postedStart, postedEnd}}
status_basis ["sent"]
totals reportable_total, reportable_payment_count, recipient_count,
flagged_count, needs_review_total, needs_review_count,
reportable_total_upper_bound (= reportable_total + needs_review_total),
unclassified_count, transactions_scanned,
duplicates_dropped (transaction rows), recipient_duplicates_dropped
recipients[] display_name, recipient_id (known recipient) | null, counterparty_id | null,
grouping (counterparty_id | name | transaction), confidence (high | medium | low),
total, payment_count, by_method {label: {count, total}}, flagged,
possible_same_payee [other counterparty ids with the same normalised name],
name_merged_total, flagged_for_review
needs_review {linked_account_transfers: [...], unlabeled_debits: [...]}; each entry:
display_name, counterparty_id | null, count, total, by_kind {kind: {count, total}},
would_flag (total >= threshold), sample_transaction_ids (max 3), hint (fixed string),
possible_same_payee [ids], name_merged_total, would_flag_merged
unclassified[] id, kind, status, amount, postedAt, counterpartyName, reason
excluded_summary {category: {count, amount (signed, as returned by Mercury)}}
fallback_to_createdAt_count は、postedAt がなく、代わりに createdAt に基づいて配置された集計対象行の数です。このような行は posted 日付フィルターでは取得されないため、通常この数は0です。ヒントは kind と Mercury の名前プレフィックスに応じて選ばれる固定文字列です。取引相手のテキスト自体はデータであり、指示として扱われることはありません。
list_tax_docs
戻り値：
entity
document_count, recipient_count, recipients_with_docs
duplicates_dropped {attachments, recipients}
documents[] id, recipientId, recipientName | null, fileName (verbatim third-party text),
formType (w9 | w8BEN | w8BENE | unknown | null), uploadedAt
recipients_without_docs[] id, name | null, status | null (every recipient of any status with no attachment)
ダウンロード URL は返されません。
キープアライブ
uvx --from 'mercury-multiorg-mcp==0.1.6' mercury-multiorg-mcp-keepalive --entities /private/path/entities.yaml
キープアライブの実行ファイル名はパッケージ名と異なるため、uvx では
--from が必要です。クローンからは、uv run mercury-multiorg-mcp-keepalive を実行すると
同じコマンドを実行できます。
設定されたエンティティごとに認証済みの GET /accounts を 1 回実行し、それぞれ 1 行
（<timestamp> OK|FAIL <entity> HTTP <status>）を出力します。いずれかのエンティティで失敗した場合、またはトークンを持つエンティティがない場合は終了コード 1、設定エラーの場合は終了コード 2 です。ホストのルールはサーバーと同じです（本番環境、サンドボックス、ループバック以外では --allow-custom-api-base を指定します）。詳細、実行間隔、cron / launchd の設定例については
docs/keepalive.md をご覧ください。
開発
uv sync
uv run pytest
テストでは合成 JSON フィクスチャとモック HTTP トランスポートのみを使用します。 このパッケージ、そのテスト、またはその履歴には、実在する氏名、トークン、口座識別子を含めてはなりません（上記の履歴に関する注記に記載されている、過去の例外である公開銀行ルーティング番号 1 件を除きます）。
ライセンス
MIT です。LICENSE をご覧ください。このファイルもパッケージに含まれています。
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。