🚀 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进行身份验证，可通过反向代理进行速率限制。