Faxdrop Mcp

📠 faxdrop-mcp

MCP 対応の AI アシスタントから、実際のファクスを送信できます。FaxDrop HTTP API をラップしています。

AI アシスタント（Claude、Cursor、Continue、OpenClaw など）からFaxDrop API経由で実際のファクスを送信できる Model Context Protocol（MCP）サーバーです。

✨ この MCP を選ぶ理由

米国の医療機関や政府の書類、さらに多くの法律・金融関連のワークフローでは、今もファクスが必要とされています。FaxDrop は、使いやすい HTTP API と無料枠（月 2 件のファクス送信）を提供するホステッドファクスサービスです。この MCP は、エージェントプラットフォームに実際に必要な安全対策を備えて、LLM から利用できるようにします。

🤔 FaxDrop API を直接呼び出すだけではだめですか？

できます。ただし、直接呼び出すエージェントは、毎回同じ一連のガードを再実装することになります。この MCP を使えば、次の機能をそのまま利用できます。

• 入力の検証 — アップロード前に、絶対パス、拡張子、10 MB の上限を検証します（ファイルを開く前にすべて実施）。FAX 番号には E.164 正規表現を適用し、SSRF とパストラバーサルを防ぎます。
• TOCTOU に安全な読み込み — fs.open() でファイル記述子を固定し、読み込み中もサイズを継続的に検証します。
• シークレットの漏えい防止 — エラーオブジェクトからレスポンス本文を除外します。監査ログには、FaxDrop のレスポンス形式に含まれる明示的な許可リストのフィールド（recipientNumber、faxId、id）だけをそのまま記録し、認証情報のセット（apiKey / authorization / password / …）を遮断します。それ以外のフィールドはすべて、長さを示すマーカー（[ELIDED:NNN]）に置き換えます。fast-check でプロパティベーステスト済みです。
• ドライランと監査ログ — FAXDROP_MCP_DRY_RUN=true で送信せずにプロンプトをテストできます。FAXDROP_MCP_AUDIT_LOG=/abs/path で JSONL 形式の記録を出力します（モード 0o600）。
• 明確なエラー — FaxDrop の 402 / 429 / 4xx を、error_type、hint、retry_after を含む MCP の isError として返します。
• あらゆる MCP クライアントにそのまま導入可能 — Claude Desktop / Code / Cursor / Continue / OpenClaw に、npx -y faxdrop-mcp の 1 行を追加するだけです。
• 検証可能なリリース — Sigstore 署名済み + SLSA in-toto アテステーション + npm provenance（検証方法）。

約 12 KB のラッパーで、1 週間かかるセキュリティレビューを設定変更 1 行で済ませられます。

📦 インストール

npm install -g faxdrop-mcp

または、npx で直接実行します。

npx faxdrop-mcp

⚙️ 設定

サーバーは環境変数 FAXDROP_API_KEY を読み込みます。faxdrop.com/account（Developer API → Generate Key）でキーを取得してください。キーは fd_live_<32 hex> の形式です。

🤖 Claude Desktop / Claude Code

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

{
  "mcpServers": {
    "faxdrop": {
      "command": "npx",
      "args": ["-y", "faxdrop-mcp"],
      "env": {
        "FAXDROP_API_KEY": "fd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

🖱️ Cursor

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

{
  "mcpServers": {
    "faxdrop": {
      "command": "npx",
      "args": ["-y", "faxdrop-mcp"],
      "env": {
        "FAXDROP_API_KEY": "fd_live_..."
      }
    }
  }
}

🦀 OpenClaw

~/.openclaw/openclaw.json に追加し、ゲートウェイを再起動します（docker restart openclaw-openclaw-gateway-1 または同等のコマンド）。

🛠️ ツール（3）

📤 faxdrop_send_fax

FAX を送信します。ローカルのドキュメントを送信ボックス（デフォルトは ~/FaxOutbox/）からアップロードし、国際形式（E.164）の FAX 番号に送信します。

必須：

• filePath（文字列、絶対パス）— PDF、DOCX、JPEG、PNG、10 MB 以下。送信ボックス内に置く必要があります。
• recipientNumber（文字列）— E.164 形式（例：+12125551234）。3 層の電話番号ゲート（TYPE → COUNTRY → 番号ごとのチェック）の対象です。
• senderName（文字列）
• senderEmail（文字列）

オプションのカバーページ項目（includeCover が true の場合のみ印字されます）：

• includeCover（ブール値）— 無料アカウントでは常にブランド付きカバーが含まれます。有料アカウントではデフォルトで false です。
• coverNote（文字列、500 文字以下）— メッセージ本文
• recipientName（50 文字以下）、subject（200 文字以下）、senderCompany（100 文字以下）、senderPhone（検証済みの E.164 形式）

通知：

• sendEmail（ブール値）— FaxDrop から送信者に FAX ごとの配信確認メールを送るかどうかを指定します。デフォルトは false（送信しない）です。この MCP はバッチ処理やエージェントのワークフロー向けに構築されており、FAX ごとにメールを送ると受信トレイがあふれるためです。同じ情報は faxdrop_get_fax_status から取得できます。メールを受け取るには true に設定します。FAX の送信失敗メール、運用担当者へのアラート、返金、ステータスページには影響しません。送信レスポンスには deliveryEmail: enabled | suppressed が含まれます。

戻り値： { success, faxId, status, statusUrl, deliveryEmail }

🔗 faxdrop_pair_number

FAX 番号をペアリング済み許可リスト（~/.faxdrop-mcp/paired.json）に追加します。FAXDROP_MCP_NUMBER_GATE=pairing（デフォルト）の場合のみ有効です。この番号も TYPE と COUNTRY のチェックに合格する必要があり、バイパスはできません。ペアリング済みの番号は番号ごとの承認なしで FAX を送信できるため、ペアリングする前に必ずユーザーに確認してください。

必須：

• recipientNumber（文字列）— E.164 形式

戻り値： { paired, country, type }

📊 faxdrop_get_fax_status

以前に送信したファクスの配信状況を確認します。完了状態（delivered / failed / partial）はプロセス全体でキャッシュされます（LRU 100 件、許可リストでスライス）。完了したファクスを再度ポーリングすると、_cached: true マーカーを付けて即時に応答し、FaxDrop の利用枠を節約します。

推奨されるポーリング間隔：最初の 2 分間は約 5 秒ごと、その後は最長 10 分まで約 30 秒ごとにポーリングし、完了状態になったら停止してください。

必須項目：

• faxId（文字列）

戻り値： { id, status, recipientNumber?, pages?, completedAt?, _cached? }

🛡️ セーフガード

設定項目	環境変数	デフォルト	備考
送信ボックスの制限	FAXDROP_MCP_WORK_DIR=/abs/path	~/FaxOutbox/（モード 0o700 で自動作成）	realpath による正規化後、すべての filePath がこのディレクトリ内にある必要があります。送信ボックス外へのシンボリックリンクは拒否されます。
番号ゲート	FAXDROP_MCP_NUMBER_GATE=open|pairing|closed	pairing	pairing では、新しい番号にファクスを送信する前に faxdrop_pair_number を介した HITL 承認が必要です。closed では実行時のペアリングが無効になります（paired.json は別途編集してください）。
許可する種類	FAXDROP_MCP_ALLOWED_TYPES=...	FIXED_LINE,FIXED_LINE_OR_MOBILE,VOIP,TOLL_FREE	libphonenumber の NumberType 許可リストです。
許可する国	FAXDROP_MCP_ALLOWED_COUNTRIES=...	US,CA,PR,GU,VI,AS,MP	ISO-3166-1 alpha-2 の許可リストです（US/CA と米国領）。
状態ディレクトリ	FAXDROP_MCP_STATE_DIR=/abs/path	~/.faxdrop-mcp/（モード 0o700）	paired.json の保存場所です（モード 0o600、アトミック書き込み）。
ドライラン	FAXDROP_MCP_DRY_RUN=true	オフ	書き込みツール（faxdrop_send_fax、faxdrop_pair_number）は、送信される予定のペイロードを返します（下の行を参照。監査ログと同じ許可リストベースの秘匿処理が適用されます）。FaxDrop を呼び出したり、paired.json に触れたりすることはありません。
監査ログ	FAXDROP_MCP_AUDIT_LOG=/abs/path/audit.log	オフ	追記専用の JSON Lines（ファイルモード 0o600）です。許可リストベースの秘匿処理により、FaxDrop のレスポンス形式のフィールド（recipientNumber、faxId、id）のみがそのまま保持されます。既知の認証情報キー（apiKey / authorization / password / secret / token）は [REDACTED] に置き換えられ、それ以外のすべてのフィールドは長さマーカー [ELIDED:NNN] とともに省略されます。これはフェイルクローズ設計です。上流で新しい API フィールドが追加されても、漏えいせず、デフォルトで非表示になります。

⚠️ エラーカタログ

すべての失敗は、構造化された error_type、message、および該当する場合は hint と retry_after を含む isError: true として返されます。プログラムによる処理では、error_type（structuredContent 内）に基づいて判定し、再試行ロジックを実行できます。

error_type	レイヤー	発生条件	推奨される対応
phone_parse	入力	libphonenumber で宛先番号を解析できません。	E.164 形式の番号をユーザーに尋ねます。
phone_type	ポリシー	電話の種類（例：MOBILE）が FAXDROP_MCP_ALLOWED_TYPES に含まれていません。	ファクス回線を使用するか、環境変数を拡張します。
phone_country	ポリシー	国が FAXDROP_MCP_ALLOWED_COUNTRIES に含まれていません。	ユーザーに確認し、意図した設定であれば環境変数を拡張します。
phone_gate	ポリシー	番号が paired.json に登録されておらず、ゲートが pairing または closed です。	pairing モードの場合：最初に faxdrop_pair_number を呼び出します。closed の場合：別の手段で paired.json を編集します。
pair_disabled	ポリシー	faxdrop_pair_number が pairing モード以外で呼び出されました。	FAXDROP_MCP_NUMBER_GATE=pairing を設定します。
bad_request	ファイルシステム	パスが相対パス、outbox の外、リーフシンボリックリンク、存在しないパス、サイズ超過、または未対応の拡張子です。	付随する hint に具体的な対処方法が記載されています。
unauthorized	上流	FaxDrop が 401 を返しました。	MCP クライアントの設定で FAXDROP_API_KEY を確認します。
payment_required	上流	FaxDrop が 402（クレジット不足）を返しました。	FaxDrop の料金ページでチャージします。
rate_limited	上流	FaxDrop が 429 を返しました。	retry_after 秒待ちます。hint に制限されたバケットが表示されます。
invalid_response	上流	FaxDrop が JSON 以外の本文を返しました（プロキシによる傍受、インシデントページなど）。	安全のため本文は破棄されます。FaxDrop のステータスページを確認してください。
fax_error	上流（フォールバック）	FaxDrop が error_type フィールドなしでエラーを返しました。	メッセージを確認し、一時的なエラーとして扱います。

🚦 レート制限とクォータ

すべてのファクス送信には、FaxDrop によって適用される独立した 2 種類の上限があります。

• キーごとのレート制限（1 分／1 時間／1 日単位のバケット）— retry_after と X-RateLimit-* ヘッダーを含む 429 rate_limited。
• アカウントのクレジット残高 — 残高がなくなると、チャージを促すヒントを含む 402 payment_required。

MCP は独自のリミッターを追加しません。FaxDrop の応答を、error_type、hint、retry_after を含む isError: true としてそのまま転送します。現在の数値については、FaxDrop の API ドキュメントを参照してください。

🔒 セキュリティ

• faxdrop_send_fax を呼び出す前に、必ずユーザーに確認してください（宛先、ファイル、カバーページ）。これはツールの説明にも明記されています。
• MCP はユーザーのローカルファイルシステムからファイルを読み取ります。このサーバーを公開するのは、信頼できるエージェントのみにしてください。
• FAXDROP_MCP_DRY_RUN=true を設定して、プロンプトを安全にテストできます。
• DNS に自ら応答するローカルプロキシの背後（拡張モードの Surge は 198.18.0.0/15 を割り当てます）では、SSRF ガードがそのアドレスを許可するよう MCP_TRUSTED_CIDRS=198.18.0.0/15 を設定してください。プロキシが対応している場合は、単一の IP を指定することを推奨します。起動時に拒否される設定：不正なエントリー、合計 131,072 個を超えるアドレス（単一範囲の場合：IPv4 は最大 /15、IPv6 は最大 /111）、ループバック、リンクローカル、0.0.0.0/8 に該当するもの、または IPv4 を含む IPv6 範囲（::ffff:10.47.83.1 のような IPv4 マップアドレスは、その IPv4 として扱われます）。
• 脆弱性の報告手順については、SECURITY.md を参照してください。

🗺️ ロードマップ

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

🌐 エコシステム

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

• 📧 klodr/gmail-mcp — Gmail
• 📠 klodr/faxdrop-mcp — FaxDrop 経由で実際のファクスを送信できます（このプロジェクトです）
• 🏦 klodr/mercury-invoicing-mcp — Mercury の銀行サービスと請求書発行

🤝 コントリビューション

プルリクエストを歓迎します。テスト／ビルド／リンティングのチェックリストとリリース手順については、CONTRIBUTING.md を参照してください。

📄 ライセンス

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