Mercury Invoicing Mcp

🏦 mercury-invoicing-mcp

Mercury バンキング MCP サーバーです。Invoicing API を完全にサポートしており、Mercury の売掛金エンドポイントを公開する初の MCP です。

AI アシスタント（Claude、Cursor、Continue など）から Mercury の法人向け銀行口座にプログラム経由で完全にアクセスできる Model Context Protocol（MCP）サーバーです。ほかの Mercury MCP にはない Invoicing API（単発および定期請求書）も利用できます。

✨ この MCP が選ばれる理由

機能	Mercury 公式 MCP	dragonkhoi/mercury-mcp	mercury-invoicing-mcp
銀行情報の読み取り（口座、取引、明細書）	✅	✅	✅
銀行操作の書き込み（send_money、受取人）	❌	✅	✅
Mercury の自分の口座間の内部振替	❌	❌	✅
Invoicing API（作成、更新、キャンセル、添付ファイル）	❌	❌	✅
顧客の売掛金管理＋定期請求書	❌	❌	✅
Webhook の完全な CRUD（update_webhook を含む）	❌	❌	✅
組み込みの安全対策（レート制限、ドライラン、機密情報をマスキングした監査ログ）	❌	❌	✅
安定したトークン（頻繁な再認証が不要、IP 許可リストに対応）	❌	✅	✅
オープンソース（MIT）	❌	✅	✅
Node.js の最低バージョン	該当なし（ホスト型）	❌ Node 14 は 2023 年に EOL	✅ LTS（>=24.18.1）、24 および 26 でテスト済み
公開されるツールの合計数	約10	約11	39

読み取り専用の情報確認には、Mercury 公式 MCP をおすすめします。請求書を自動化する、Mercury に書き込みを行う、または Mercury を LLM エージェントに安全に公開する場合は、こちらをご利用ください。

📦 インストール

npm install -g mercury-invoicing-mcp

または、npx で直接利用できます。

npx mercury-invoicing-mcp

⚙️ 設定

サーバーは環境変数から MERCURY_API_KEY を読み取ります。Mercury Settings → API Tokens で API キーを取得してください。

🔑 トークンの権限を適切に設定する

Mercury では、トークンの作成時にリソースごとに細かくスコープを設定できます。読み取り／書き込みを切り替える単一の設定ではありません。ユースケースに必要な権限だけを選択すると、残りは Mercury がサーバー側で制御します。適切なスコープなしで呼び出されたツールは 403 を返し、MCP は分かりやすい isError: true の応答として通知します（該当する場合は Mercury Plus に関するヒントも表示されます）。

トークンの作成時に、次の項目を選択します。

• トークンが参照できるアカウント（一つ、複数、またはすべて）。
• リソースの種類ごとの読み取りまたは書き込み権限：Accounts、Transactions、Recipients、Send Money、Cards、Statements、Treasury、Invoicing（AR）、Webhooks。

この MCP でよく使われるスコープ設定：

ユースケース	付与するスコープ
読み取り専用の参照（ダッシュボード、チャットチャネルのボット）	accounts、transactions、statements、cards、treasury の読み取りのみ。それ以外は付与しない
帳簿管理（取引のカテゴリ分類）	すべてのリソースの読み取り権限＋transactions の書き込み権限（update_transaction 用）
請求書の自動処理	accounts の読み取り権限＋invoices、customers の書き込み権限（Mercury Plus が必要）
受取人の管理	＋recipients の書き込み権限
自分の口座間の内部振替	＋send_money の書き込み権限（create_internal_transfer で使用）
外部への送金リクエスト	＋send_money の書き込み権限（リクエストを作成します。以下の安全に関する注意を参照）
Webhooks のみの操作	webhooks の書き込み権限のみ

⚠️ 重要：外部への支払いは、Mercury に設定した承認ポリシーに左右されます

この MCP 経由で作成された外部への支払いが即時に実行されるか、人間の承認を待つかは、MCP では制御されません。Mercury ワークスペースの承認ポリシー（app.mercury.com の Settings → Approvals）によって適用されます。MCP ができるのは API 呼び出しの作成だけです。その呼び出しに対して Mercury がどう処理するかは、ワークスペースの設定によって決まります。

3 つの送金ツールはそれぞれ動作が異なります。

• mercury_request_send_money — ワークスペースのポリシーにかかわらず、Mercury に承認待ちリクエストを必ず作成します。「送信してから承認者を待つ」ワークフロー向けに設計されています。
• mercury_send_money — 支払いを送信します。ワークスペースの承認ルール（金額のしきい値、口座ごとのルール、必要な承認者）に応じて、即時に実行されるか、承認待ちになります。承認しきい値を $0 に設定したワークスペースでは、外部へのすべての支払いが Mercury の Web／モバイルアプリでの人間による承認待ちになります。より寛容な設定のワークスペースでは、少額の支払いは再承認を求められずに決済される場合があります。
• mercury_create_internal_transfer — 同じ Mercury 組織内で、すでに所有している 2 つの口座間で資金を移動します。外部の受取人は関与せず、承認ワークフローもありません。

→ エージェントに書き込みツールを公開する場合は、Mercury で厳格な承認ポリシーを設定してください（例：金額にかかわらず、外部へのすべての支払いに承認を必須にする）。MCP の呼び出しごとのレート制限とドライランモードも多重防御として役立ちますが、最終的な制御手段は Mercury の承認ポリシーです。プロンプトインジェクションを受けたエージェントが send_money を呼び出した場合、その呼び出しの安全性は、同じペイロードが他の API クライアントから届いたときに Mercury がどう処理するかに完全に依存します。

🧪 サンドボックスモード

Mercury のサンドボックス環境（実際のお金は使わず、ダミーデータが事前に用意されています）でテストするには、サンドボックス用トークンを使用するだけです。

MERCURY_API_KEY=secret-token:mercury_sandbox_xxxxxxxxxxxxxxxx

MCP は mercury_sandbox_ で始まるサンドボックストークンを自動検出し、自動的に https://api-sandbox.mercury.com/api/v1 を接続先に設定します。

ベース URL を明示的に上書きする場合（例：セルフホストのプロキシを使用する場合）：

MERCURY_API_BASE_URL=https://your-proxy.example.com/api/v1

🛡️ DNS に独自の応答を返すローカルプロキシを使用している場合

一部のプロキシは、DNS に独自のアドレスを返します（Surge は拡張モードで 198.18.0.0/15 を割り当てます）。SSRF ガードは、パブリックではないアドレスと同様に、これらのアドレスも拒否します。そのプロキシを信頼する場合は、その範囲を指定してください。

MCP_TRUSTED_CIDRS=198.18.0.0/15

カンマ区切りの IP または CIDR 範囲を指定します。プロキシが許可する場合は、単一の IP を指定してください。起動時に拒否されるのは、不正な形式のエントリー、合計で 131,072 個を超えるアドレス（単一の範囲では IPv4 は最大 /15、IPv6 は最大 /111）、ループバック、リンクローカル、0.0.0.0/8、または IPv4 を含む IPv6 範囲に該当するアドレス（::ffff:10.47.83.1 のような IPv4 マップアドレスは、その IPv4 アドレスとして扱われます）です。これらの範囲内のアドレスはガードによるチェックの対象外となり、信頼の判断はプロキシに委ねられます。未設定の場合、例外はありません。

🤖 Claude Desktop / Claude Code

~/Library/Application Support/Claude/claude_desktop_config.json（Claude Code の場合は ~/.claude.json）に追加します。

{
  "mcpServers": {
    "mercury-invoicing": {
      "command": "npx",
      "args": ["-y", "mercury-invoicing-mcp"],
      "env": {
        "MERCURY_API_KEY": "secret-token:mercury_production_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

🖱️ Cursor

~/.cursor/mcp.json に追加します。

{
  "mcpServers": {
    "mercury-invoicing": {
      "command": "npx",
      "args": ["-y", "mercury-invoicing-mcp"],
      "env": {
        "MERCURY_API_KEY": "secret-token:..."
      }
    }
  }
}

🦀 OpenClaw

OpenClaw は、@modelcontextprotocol/sdk を介して MCP をサポートする、オープンソースのセルフホスト可能なエージェントプラットフォームです。~/.openclaw/openclaw.json に追加します。

{
  "mcpServers": {
    "mercury-invoicing": {
      "command": "npx",
      "args": ["-y", "mercury-invoicing-mcp"],
      "env": {
        "MERCURY_API_KEY": "secret-token:..."
      }
    }
  }
}

ゲートウェイを再起動します（docker restart openclaw-openclaw-gateway-1 または同等のコマンドを実行します）。すべてのツールが、すべての OpenClaw エージェントで利用できるようになります。

ヒント：信頼できないチャネル（WhatsApp、Telegram、Slack、受信メールなど）に公開するエージェントには、そのチャネルで実際に必要なスコープのみをトークンに付与してください。送金には引き続き Mercury アプリで人間による明示的な承認が必要ですが、スコープを最小限にすることで、不要な通知（誤った保留中リクエスト）を避け、読み取りを通じて攻撃者が持ち出せる情報を減らせます。ユースケース別の設定例については、トークンの適切なスコープ設定を参照してください。

🛠️ ツール（全 39 個）

🏦 銀行 — 口座

• mercury_list_accounts、mercury_get_account
• mercury_list_cards
• mercury_get_organization
• mercury_list_categories

💳 銀行 — IO クレジット

• mercury_list_credit_accounts — Mercury API リファレンスのCredit › すべてのクレジット口座を一覧表示に記載されている GET /credit を呼び出します。IO クレジットカード口座を返します。これらは mercury_list_accounts によってサーバー側で除外されます。
• mercury_list_credit_transactions — IO クレジットの取引（保留中のカード利用承認を含む）に使用される 単数形のパス GET /account/{id}/transactions を呼び出します。注：預金口座に使用される複数形の /accounts/{id}/transactions とは異なります。
• mercury_list_credit_statements — GET /api/v2/account/{id}/statements を呼び出します。IO クレジットの明細は v2 エンドポイントでのみ提供されます。v1 の明細パスは、クレジット口座に対して 404 を返します。

💸 銀行 — 取引

• mercury_list_transactions、mercury_get_transaction
• mercury_get_transaction_attachment — 領収書のダウンロード URL を返す唯一のツールです
• mercury_update_transaction（メモ、カテゴリ）
• mercury_send_money、mercury_request_send_money
• mercury_create_internal_transfer（自分の Mercury 口座間での振替）

取引一覧は、デフォルトで 簡潔な形式に絞ったデータを返します。識別用のフィールドに加えて hasAttachment が含まれるため、領収書がまだ添付されていない取引を確認できます。実際の口座で測定したところ、Mercury の生のレスポンスと比べてペイロードを約 20% に削減できます。添付 URL 以外のすべてのフィールドを取得するには、detail: "full" を指定してください。どのモードでも添付 URL は返されません。

領収書の URL は、どちらのモードでも取引のペイロードに 含まれることはありません。Mercury の URL は S3 の事前署名リンクで、それぞれ約 2.4 kB あり、約 12 時間にわたって認証なしでドキュメントにアクセスできるベアラー認証情報です。読み取りのたびに URL を返すと、ペイロードの大部分を占めるだけでなく、短期間だけ有効な認証情報がログやモデルコンテキストに散らばってしまいます。必要な場合は、取引ごとに mercury_get_transaction_attachment を使って明示的に取得してください。

👥 銀行 — 受取人

• mercury_list_recipients、mercury_add_recipient、mercury_update_recipient

📊 銀行 — 明細

• mercury_list_statements

🏛️ 財務

• mercury_get_treasury
• mercury_list_treasury_transactions
• mercury_list_treasury_statements

🧾 請求書（売掛金）

⚠️ Mercury Plus プランが必要です。 請求書および顧客（AR）API は、Mercury の Plus プラン以上でのみ利用できます。Free または Standard プランでは、これらのツールを呼び出すと 403 Forbidden が返されます。その他のツール（銀行、財務、Webhook）はすべてのプランで利用できます。

• mercury_list_invoices、mercury_get_invoice
• mercury_create_invoice、mercury_update_invoice
• mercury_cancel_invoice
• mercury_list_invoice_attachments
• mercury_get_invoice_pdf — Mercury の文書化された getinvoicepdf エンドポイント（{baseUrl}/ar/invoices/{id}/pdf、認証が必要、サンドボックス／プロキシで安全）を介して、請求書 PDF のダウンロード URL を返します。手動でアップロードされたファイルのみを一覧表示する mercury_list_invoice_attachments とは異なります。

👤 顧客（AR）— こちらも Mercury Plus が必要です

• mercury_list_customers、mercury_get_customer
• mercury_create_customer、mercury_update_customer、mercury_delete_customer

🔗 Webhook

• mercury_list_webhooks、mercury_get_webhook
• mercury_create_webhook、mercury_update_webhook、mercury_delete_webhook

まだラップされていないエンドポイント — Mercury は約22個の追加エンドポイントを公開していますが、この MCP ではまだ対応していません。今後のリリースで追加予定です。 対応予定：明細書 PDF のダウンロード（getstatementpdf — 請求書 PDF はすでに mercury_get_invoice_pdf で対応済み）、添付ファイル （uploadtransactionattachment、uploadrecipientattachment、 getattachment、listrecipientsattachments）、Webhook 署名の 検証（verifywebhook）、Webhook イベント（getevent、getevents）、 送金の承認（listsendmoneyapprovalrequests、 getsendmoneyapprovalrequest）、ユーザー（getuser、getusers）、 Mercury Raise SAFE（getsaferequest(s)、getsaferequestdocument）、 OAuth フロー（obtainaccesstoken、startoauth2flow）。

Mercury は list_send_money_requests、COA テンプレート、 または Journal Entries を公開 API で一切公開していません。これらの機能は ダッシュボードでのみ利用できます。

send_invoice エンドポイントは（API にもダッシュボードにも）存在しません。 請求書の作成時に sendEmailOption: "SendNow" を指定した場合にのみ、 請求書のメールが送信されます。後からコピーを送るには、 mercury_get_invoice_pdf で請求書の PDF URL を取得し、ダウンロードして、 手動でメール送信してください。

利用できるツールは、Mercury API トークンのスコープによって異なります。サーバーは 39個すべてのツールを登録しますが、Mercury は API レベルで 許可されていない操作を拒否します。

🗺️ ロードマップ

ROADMAP.md を参照してください。

🔒 セキュリティ

• API キーを決して共有しないでください。 環境変数を使用し、CLI 引数は使用しないでください。
• 書き込みアクセスが不要な場合は、読み取り専用またはスコープを限定したトークンを使用してください。
• 信頼できないコンテンツを読み取る LLM に書き込みツールを公開する際は、プロンプトインジェクションのリスクに注意してください。Anthropic の MCP セキュリティガイダンスを参照してください。

🛡️ 組み込みの保護機能

この MCP には、書き込みツールで自動的に有効になる3つのミドルウェア層が含まれています（読み取りツールには影響しません）。

1️⃣ レート制限（2つのウィンドウ）

各書き込みツールはバケットに割り当てられます。各バケットでは、2つのローリングウィンドウ（1日の上限（24時間）と1か月の上限（30日間のローリング））が同時に適用されます。どちらかのウィンドウが上限に達すると、呼び出しは直ちに拒否されます。そのため、エージェントが数週間かけてペースを調整し、1日の上限を守っていたとしても、暴走してアカウントの利用枠を使い切ることはありません。

バケット	ツール	1日あたり	1か月あたり（30日）
payments	send_money, request_send_money	7	150
internal_transfer	create_internal_transfer	2	40
invoices_write	create_invoice, update_invoice	10	200
invoices_cancel	cancel_invoice	3	30
customers_write	create_customer, update_customer, delete_customer	3	60
recipients_add	add_recipient	3	45
recipients_update	update_recipient	2	15
transactions_update	update_transaction（記帳、タグ付け、領収書）	50	500
webhooks_create	create_webhook	2	15
webhooks_update	update_webhook	2	15
webhooks_delete	delete_webhook	2	15

バケットごとの上書き（両方のウィンドウを指定する必要があります）：

MERCURY_MCP_RATE_LIMIT_payments=15/day,300/month   # larger supplier batch
MERCURY_MCP_RATE_LIMIT_invoices_write=20/day,400/month  # large monthly billing run
MERCURY_MCP_RATE_LIMIT_DISABLE=true                # disable all rate limiting (not recommended)

上限を超えると、ツールは構造化JSONペイロードを含む isError: true レスポンスを返します。source と error_type のプレフィックスにより、これがローカルのMCPセーフガードであることが明確になります。呼び出しはMercuryに送信されていません。Mercuryで実際に発生した429は、別途 "Mercury API error 429: ..." として通知されます。

{
  "source": "mcp_safeguard",
  "error_type": "mcp_rate_limit_daily_exceeded",
  "message": "MCP Rate Limit Exceeded — Daily (local safeguard, not a Mercury API error)",
  "hint": "Daily Limit Exceeded: mercury_send_money (bucket: payments) capped at 7 per 24h. Retry in ~180 min. Override with MERCURY_MCP_RATE_LIMIT_payments=D/day,M/month if this is a legitimate batch.",
  "retry_after": "2026-04-22T00:00:00.000Z"
}

error_type は mcp_rate_limit_daily_exceeded または mcp_rate_limit_monthly_exceeded のいずれかです。これによりエージェントは、MCPのローカル上限とサーバー側のMercury制限を混同せず、適切な粒度で呼び出しを控えることができます。

レート制限のウィンドウは、プロセスの再起動後も保持されます。状態は ~/.mercury-mcp/ratelimit.json に保存されます（モード 0o600）。ホスト間で状態を共有する場合や、特定のボリュームに固定する場合は、MERCURY_MCP_STATE_DIR=/abs/path で保存先を上書きしてください。永続化しない場合、セッションごとにサーバーを再起動するMCPホストでは、気付かないうちに制限が回避されてしまいます。

2️⃣ ドライランモード

Mercuryを実際に呼び出さずに、エージェントが実行するはずの操作を確認できます。動作が疑わしい場合のデバッグや、ステージングで役立ちます。

MERCURY_MCP_DRY_RUN=true

書き込みツールはMercury APIを呼び出さずに、実行予定の操作を説明する構造化ペイロードを返します。

3️⃣ 監査ログ（オプトイン）

すべての書き込み呼び出しについて、構造化JSONログを有効にします。

MERCURY_MCP_AUDIT_LOG=/var/log/mercury-mcp-audit.log

各行は {ts, tool, result, args} です（1行につきJSONオブジェクト1つ）。結果は ok、dry-run、error のいずれかです。パスは絶対パスである必要があります。args 内の機密フィールド（accountNumber、routingNumber、apiKey、authorization、password、token、secret、ssn）は自動的に伏せられます。ファイルはモード 0600（所有者のみ読み書き可能）で作成されます。

🔧 開発

git clone https://github.com/klodr/mercury-invoicing-mcp.git
cd mercury-invoicing-mcp
npm install
npm run build
npm test

💡 インスピレーション

• @stripe/mcp — アーキテクチャパターン
• dragonkhoi/mercury-mcp — 初期の銀行業務ツールの実装
• Official Mercury MCP — 読み取り専用のリファレンス

🌐 エコシステム

klodrファミリーのその他のMCPサーバー：

• 📧 klodr/gmail-mcp — Gmail
• 📠 klodr/faxdrop-mcp — FaxDrop経由で実際のファックスを送信
• 🏦 klodr/mercury-invoicing-mcp — Mercuryの銀行業務と請求書管理（このリポジトリです）

📄 ライセンス

MIT — LICENSEを参照してください。

🤝 コントリビューション

IssueやPRを歓迎します。テスト／ビルド／カバレッジのチェックリストとリリースプロセスについては、CONTRIBUTING.mdを参照してください。