Faxbot

🚀 Faxbot

The first and only open - source, self - hostable fax API. With a single function call, you can send faxes, offering a seamless solution for your faxing needs.

🚀 Quick Start

The first and only open - source, self - hostable fax API. Send faxes with a single function call.

Yes, this repo might seem overwhelming initially. That's because Faxbot supports multiple backends (cloud and self - hosted), several MCP transport options for AI integration, and HIPAA - compliant security configurations. However, most users will only need one straightforward path through this complexity.

Core function: send_fax(phone_number, pdf_file) → Done.

✨ Features

Why Faxbot

• Open - source and self - hostable end - to - end: You can run it entirely on your infrastructure and modify it as needed.
• One API, many backends: Switch between Phaxio, Sinch, and self - hosted SIP/Asterisk via environment settings.
• Bring - your - own SIP trunk: Choose any SIP provider and migrate later by changing a couple of environment variables.
• Fully local option: When using SIP, there is no third - party cloud involved, and artifacts stay on your storage (S3/MinIO supported).
• AI assistant tools built - in: MCP servers (Node & Python) for stdio/HTTP/SSE; desktop stdio supports filePath (no base64 size pain).
• Inbound receiving design: Cloud webhooks with signature verification or Asterisk ReceiveFAX → TIFF→PDF, mailbox routing, short - TTL tokens, retention.
• Test/dev backend: Simulate send/receive flows without using a paid provider.
• Vendor - neutral SDKs: Identical Node/Python clients make your app code portable.

If you have questions or issues, please don't hesitate to reach out. See CONTRIBUTING.md for the best way to get help.

📦 Installation

Quick Start Options

Docker Compose (API + optional MCP)

• Copy and edit .env (or start from .env.example).
• Run the API:

docker compose up -d --build api

• Optional MCP (HTTP, port 3001):

docker compose --profile mcp up -d --build faxbot - mcp
# or: make mcp - up

• Optional MCP SSE (OAuth2/JWT, port 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
# or: make mcp - sse - up

• Check health: curl http://localhost:8080/health
• Readiness: curl -i http://localhost:8080/health/ready (200 when ready; 503 if not)
• MCP HTTP health: curl http://localhost:3001/health
• MCP SSE health: curl http://localhost:3002/health

Option 1: Phaxio (Recommended for Most Users)

• 5 - minute setup
• No telephony knowledge required
• Pay per fax (cloud)

→ Phaxio Setup Guide

Option 2: Sinch Fax API v3 (Cloud)

• Direct upload model (no PUBLIC_API_URL fetch)
• Works with “Phaxio by Sinch” accounts
• Requires Project ID + API key/secret

→ Sinch Setup Guide

Option 3: Self - Hosted SIP/Asterisk

• Full control
• No per - fax cloud charges
• Requires SIP trunk and T.38 knowledge

→ SIP Setup Guide

💻 Usage Examples

Core Function

# The core function to send a fax
send_fax(phone_number, pdf_file)

📚 Documentation

Core guides

• MCP Integration — Claude/Cursor stdio, HTTP, SSE (Node + Python)
• API Reference — Endpoints and examples
• Client SDKs — Python and Node SDK usage
• MCP Inspector: use docker compose --profile mcp up -d mcp - inspector and open http://localhost:6274 to explore tools/resources/prompts

Backends

• Phaxio Setup — Cloud (tokenized PDF URL + HMAC webhook)
• Sinch Setup — Cloud direct upload (v3 API)
• SIP/Asterisk Setup — Self - hosted T.38

Security & compliance

• HIPAA Requirements — Security, BAAs, and compliance checklist
• OAuth/OIDC Setup — Configure SSE with Auth0, Okta, Azure AD, Google, Keycloak

File handling

• Images vs Text PDFs — The right way to fax scans/photos

Advanced

• Phaxio End - to - End Test — Simulated callback flow for local testing

Development status

• v3 plugin work (feature - gated) status: see docs/V3_PHASE_STATUS.md.

🔧 Technical Details

AI Assistant Integration

→ MCP Integration Guide

• Node MCP servers are in node_mcp/ (stdio, HTTP, SSE+OAuth). Python MCP servers are in python_mcp/.
• OAuth2 - protected SSE MCP servers are available in both Node and Python.

Important file - type note

• Faxbot accepts only PDF and TXT. If you have images (PNG/JPG), convert them to PDF before sending.
• Quick conversions:
  • macOS Preview: File → Export As… → PDF
  • macOS CLI: sips -s format pdf "in.png" --out "out.pdf"
  • Linux: img2pdf in.png -o out.pdf or magick convert in.png out.pdf
  • Windows: open image → Print → “Microsoft Print to PDF”.

Stdio “just works” tip

• For desktop assistants, it's recommended to use the Node or Python stdio MCP and call send_fax with filePath to your local PDF/TXT. This bypasses base64 and avoids token limits.

Client SDKs

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

→ SDK Usage Guide

Notes

• Receiving: Work in progress. Inbound scaffolding exists behind config flags and on the development branch (see PHASE_RECEIVE.md). It is not generally available yet and remains backend - isolated (Phaxio/Sinch callbacks, SIP/Asterisk internal). Outbound send is production - ready.
• Default backend: The default backend is phaxio for easier onboarding. Set FAX_BACKEND=sip explicitly for telephony users or FAX_BACKEND=sinch for Sinch v3.
• Authentication: Use X - API - Key for auth; secure it behind a reverse proxy for rate limiting.

Demo