Faxbot

🚀 Faxbot - 首个也是唯一的开源、可自托管传真 API

Faxbot 是首个且唯一的开源、可自托管传真 API，只需一次函数调用即可发送传真。尽管乍看之下这个仓库的内容可能让人有些应接不暇，但这是因为 Faxbot 支持多种后端（云服务和自托管）、多种用于 AI 集成的 MCP 传输选项，以及符合 HIPAA 标准的安全配置。不过，大多数用户只需关注其中一条适合自己的路径即可。

其核心功能仅需一个函数调用 send_fax(phone_number, pdf_file) 就能完成传真发送。

为何选择 Faxbot

• 端到端开源且可自托管：可完全在自己的基础设施上运行，并根据需求进行修改。
• 一个 API，多种后端：通过环境设置，可在 Phaxio、Sinch 和自托管的 SIP/Asterisk 之间轻松切换。
• 自带 SIP 中继：可选择任何 SIP 提供商，后续只需更改几个环境变量即可迁移。
• 完全本地化选项：使用 SIP 时，传输路径中不涉及第三方云服务，相关文件可存储在自己的存储系统中（支持 S3/MinIO）。
• 内置 AI 助手工具：提供 MCP 服务器（Node 和 Python），支持 stdio/HTTP/SSE；桌面 stdio 支持 filePath（避免 base64 大小限制问题）。
• 支持传真接收：具备云 Webhook 签名验证功能，或通过 Asterisk ReceiveFAX 将 TIFF 转换为 PDF，支持邮箱路由、短有效期令牌和文件保留。
• 测试/开发后端：可模拟发送/接收流程，无需使用付费服务提供商。
• 供应商中立的 SDK：Node 和 Python 客户端相同，应用代码具有可移植性。

如有疑问或遇到问题，请随时联系我们。查看 CONTRIBUTING.md 了解获取帮助的最佳方式。

🚀 快速开始选项

Docker Compose（API + 可选 MCP）

• 复制并编辑 .env 文件（也可从 .env.example 开始）。
• 启动 API：

docker compose up -d --build api

• 可选的 MCP（HTTP，端口 3001）：

docker compose --profile mcp up -d --build faxbot-mcp
# 或者：make mcp-up

• 可选的 MCP SSE（OAuth2/JWT，端口 3002）：

export OAUTH_ISSUER=https://YOUR_ISSUER
export OAUTH_AUDIENCE=faxbot-mcp
export OAUTH_JWKS_URL=https://YOUR_ISSUER/.well-known/jwks.json
docker compose --profile mcp up -d --build faxbot-mcp-sse
# 或者：make mcp-sse-up

• 检查健康状态：curl http://localhost:8080/health
• 检查就绪状态：curl -i http://localhost:8080/health/ready（就绪时返回 200；未就绪返回 503）
• 检查 MCP HTTP 健康状态：curl http://localhost:3001/health
• 检查 MCP SSE 健康状态：curl http://localhost:3002/health

选项 1：Phaxio（推荐大多数用户）

• 5 分钟即可完成设置
• 无需电话技术知识
• 按传真次数付费（云服务）

→ Phaxio 设置指南

选项 2：Sinch Fax API v3（云服务）

• 直接上传模式（无需获取 PUBLIC_API_URL）
• 适用于 “Phaxio by Sinch” 账户
• 需要项目 ID 和 API 密钥/密钥对

→ Sinch 设置指南

选项 3：自托管 SIP/Asterisk

• 完全自主控制
• 无需按传真次数支付云服务费用
• 需要具备 SIP 中继和 T.38 相关知识

→ SIP 设置指南

💻 AI 助手集成

→ MCP 集成指南

• Node MCP 服务器位于 node_mcp/ 目录（支持 stdio、HTTP、SSE+OAuth），Python MCP 服务器位于 python_mcp/ 目录。
• Node 和 Python 均提供支持 OAuth2 保护的 SSE MCP 服务器。

⚠️ 重要文件类型说明

• Faxbot 仅接受 PDF 和 TXT 文件。如果有图片（PNG/JPG），需先将其转换为 PDF 再发送。
• 快速转换方法：
  • macOS 预览：文件 → 导出为… → PDF
  • macOS 命令行：sips -s format pdf "in.png" --out "out.pdf"
  • Linux：img2pdf in.png -o out.pdf 或 magick convert in.png out.pdf
  • Windows：打开图片 → 打印 → “Microsoft 打印到 PDF”。

💡 Stdio 使用提示

对于桌面助手，建议使用 Node 或 Python 的 stdio MCP，并通过 filePath 参数调用 send_fax 发送本地 PDF/TXT 文件，这样可避免使用 base64 编码，从而避免令牌限制问题。

📦 客户端 SDK

• Python：pip install faxbot
• Node.js：npm install faxbot

→ SDK 使用指南

📚 详细文档

核心指南

• MCP 集成 — 支持 Claude/Cursor stdio、HTTP、SSE（Node + Python）
• API 参考 — 端点和示例
• 客户端 SDK — Python 和 Node SDK 的使用方法
• MCP 检查器：使用 docker compose --profile mcp up -d mcp-inspector 启动，然后打开 http://localhost:6274 探索工具、资源和提示信息。

后端设置

• Phaxio 设置 — 云服务（令牌化的 PDF URL + HMAC Webhook）
• Sinch 设置 — 云服务直接上传（v3 API）
• SIP/Asterisk 设置 — 自托管 T.38

安全与合规

• HIPAA 要求 — 安全、业务伙伴协议（BAAs）和合规性清单
• OAuth/OIDC 设置 — 配置 SSE 与 Auth0、Okta、Azure AD、Google、Keycloak 的集成

文件处理

• 图片与文本 PDF — 正确传真扫描件/照片的方法

高级功能

• Phaxio 端到端测试 — 本地测试的模拟回调流程

开发状态

• v3 插件工作（功能门控）状态：查看 docs/V3_PHASE_STATUS.md。

📄 注意事项

• 接收功能：仍在开发中。接收功能的框架已在配置标志和 development 分支中实现（见 PHASE_RECEIVE.md），但尚未正式发布，且目前仅在后端隔离环境中可用（Phaxio/Sinch 回调、SIP/Asterisk 内部）。外发传真功能已可用于生产环境。
• 默认后端：默认后端为 phaxio，便于新用户上手。电话用户可显式设置 FAX_BACKEND=sip，使用 Sinch v3 的用户可设置 FAX_BACKEND=sinch。
• 身份验证：使用 X-API-Key 进行身份验证，可通过反向代理进行速率限制。

演示