Faxdrop Mcp

📠 faxdrop-mcp

通过任何支持 MCP 的 AI 助手发送真实传真。封装了 FaxDrop HTTP API。

一个 Model Context Protocol（MCP）服务，让 AI 助手（Claude、Cursor、Continue、OpenClaw……）通过 FaxDrop API 发送真实传真。

✨ 为什么选择这个 MCP？

美国医疗保健、政府表格以及大量法律和金融工作流仍要求使用传真。FaxDrop 是一项托管传真服务，提供简洁的 HTTP API 和免费套餐（每月 2 份传真）。这个 MCP 将其接入大模型，并提供 Agent 平台实际需要的安全防护措施。

🤔 为什么不直接调用 FaxDrop API？

可以。但每个 Agent 最终都会重新实现同一套基本防护措施。使用这个 MCP，这些防护措施都能免费获得：

• 输入验证 — 上传前检查绝对路径、扩展名和 10 MB 上限（所有检查均在打开文件之前完成）；使用 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 错误作为 MCP isError 返回，并附带 error_type、hint、retry_after。
• 适用于任何 MCP 客户端 — 在 Claude Desktop / Code / Cursor / Continue / OpenClaw 中只需一行 npx -y faxdrop-mcp。
• 可验证的发行版本 — 由 Sigstore 签名 + SLSA in-toto 证明 + npm 来源证明（验证）。

这个约 12 KB 的封装，让原本需要一周的安全审查变成只需更改一行配置。

📦 安装

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

发送传真。将本地文档从发件箱（默认 ~/FaxOutbox/）上传到采用国际格式（E.164）的传真号码。

必填：

• 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 向发件人发送每份传真的投递确认邮件。默认为 false（不发送）——这个 MCP 面向批量处理和 Agent 工作流，每份传真都发一封邮件会塞满收件箱，而且可通过 faxdrop_get_fax_status 查询相同信息。设为 true 可重新启用邮件通知。传真发送失败邮件、操作员告警、退款和状态页面不受影响。发送响应会返回 deliveryEmail: enabled | suppressed。

返回： { success, faxId, status, statusUrl, deliveryEmail }

🔗 faxdrop_pair_number

将传真号码添加到配对允许列表（~/.faxdrop-mcp/paired.json）。仅当 FAXDROP_MCP_NUMBER_GATE=pairing（默认值）时生效。该号码仍须通过 TYPE 和 COUNTRY 检查（不可绕过）。配对前务必先征得用户确认——配对后的号码无需再次逐个审批即可发送传真。

必填：

• 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）	每个 filePath 经 realpath 规范化后都必须位于此目录内。拒绝指向发件箱外部的符号链接。
号码门控	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 允许列表（美国/加拿大及美国属地）。
状态目录	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 字段默认会被隐藏，而不会泄露。

⚠️ 错误目录

每次失败都会以 isError: true 返回，并包含结构化的 error_type、message，以及（如适用）hint 和 retry_after。程序化使用者可以根据 structuredContent 中的 error_type 进行匹配，以实现重试逻辑。

error_type	层级	触发条件	建议操作
phone_parse	输入	libphonenumber 无法解析收件人号码。	请用户提供 E.164 格式的号码。
phone_type	策略	电话类型（例如 MOBILE）不在 FAXDROP_MCP_ALLOWED_TYPES 中。	使用传真线路，或扩展环境变量。
phone_country	策略	国家/地区不在 FAXDROP_MCP_ALLOWED_COUNTRIES 中。	向用户确认；如果是有意设置，则扩展环境变量。
phone_gate	策略	号码不在 paired.json 中，且 gate 为 pairing 或 closed。	在 pairing 模式下：先调用 faxdrop_pair_number。在 closed 模式下：通过其他方式编辑 paired.json。
pair_disabled	策略	在 pairing 模式之外调用了 faxdrop_pair_number。	设置 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 强制执行：

• 每个密钥的速率限制（每分钟／每小时／每日配额桶）——返回 429 rate_limited，并附带 retry_after 和 X-RateLimit-* 标头。
• 账户信用额度余额——额度用尽时返回 402 payment_required，并附带充值提示。

MCP 不会添加自己的限流器；它会将 FaxDrop 的响应直接转发为规范的 isError: true，并包含 error_type、hint 和 retry_after。当前具体数值请参阅 FaxDrop 的 API 文档。

🔒 安全

• 调用 faxdrop_send_fax 前，务必与用户确认（收件人、文件、封面页）。这也已写入工具描述中。
• MCP 会从用户的本地文件系统读取文件——仅向你信任的 Agent 暴露此服务。
• 使用 FAXDROP_MCP_DRY_RUN=true 安全地测试提示词。
• 如果位于会自行处理 DNS 的本地代理之后（增强模式下的 Surge 会分配 198.18.0.0/15），请设置 MCP_TRUSTED_CIDRS=198.18.0.0/15，使 SSRF 防护接受其地址；如果代理允许，优先使用单个 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 银行业务和开票

🤝 贡献

欢迎提交 PR。测试／构建／lint 检查清单和发布流程请参阅 CONTRIBUTING.md。

📄 许可证

MIT — 请参阅 LICENSE。