📠 faxdrop-mcp

Send real faxes from any MCP-enabled AI assistant. Wraps the FaxDrop HTTP API.

A Model Context Protocol (MCP) server that lets AI assistants (Claude, Cursor, Continue, OpenClaw…) send real faxes through the FaxDrop API.

✨ Why this MCP?

Faxing is still required by US healthcare, government forms, and a long tail of legal/financial workflows. FaxDrop is a hosted fax service with a clean HTTP API and a free tier (2 faxes/month). This MCP exposes it to LLMs with the safeguards an agent platform actually needs.

🤔 Why not just call the FaxDrop API directly?

You can. But every agent that does ends up re-implementing the same handful of guards. This MCP gives them to you for free:

• Input validation — absolute-path + extension + 10 MB cap on the upload (all before the file is opened); E.164 regex on the fax number; no SSRF, no path traversal.
• TOCTOU-safe read — file descriptor pinned with fs.open(), size enforced continuously while reading.
• No secret leakage — error objects strip the response body; the audit log keeps only an explicit allowlist of FaxDrop response-shape fields (recipientNumber, faxId, id) in clear, blocks the credential set (apiKey / authorization / password / …), and elides every other field with a length marker ([ELIDED:NNN]). Property-tested with fast-check.
• Dry-run + audit log — FAXDROP_MCP_DRY_RUN=true to test prompts without sending; FAXDROP_MCP_AUDIT_LOG=/abs/path for a JSONL trail (mode 0o600).
• Clean errors — FaxDrop's 402 / 429 / 4xx surfaced as MCP isError with error_type, hint, retry_after.
• Drop-in for any MCP client — one npx -y faxdrop-mcp line in Claude Desktop / Code / Cursor / Continue / OpenClaw.
• Verifiable releases — Sigstore-signed + SLSA in-toto attestation + npm provenance (verify).

A ~12 KB wrapper that turns a one-week security review into a one-line config change.

📦 Installation

npm install -g faxdrop-mcp

Or use directly with npx:

npx faxdrop-mcp

⚙️ Configuration

The server reads FAXDROP_API_KEY from the environment. Get your key at faxdrop.com/account (Developer API → Generate Key). Keys look like fd_live_<32 hex>.

🤖 Claude Desktop / Claude Code

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (or ~/.claude.json for Claude Code):

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

🖱️ Cursor

Add to ~/.cursor/mcp.json:

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

🦀 OpenClaw

Add to ~/.openclaw/openclaw.json, then restart the gateway (docker restart openclaw-openclaw-gateway-1 or your equivalent).

🛠️ Tools (3)

📤 faxdrop_send_fax

Send a fax. Uploads a local document from the outbox (default ~/FaxOutbox/) to a fax number in international (E.164) format.

Required:

• filePath (string, absolute) — PDF, DOCX, JPEG, or PNG, ≤10 MB. Must live inside the outbox.
• recipientNumber (string) — E.164, e.g. +12125551234. Subject to the 3-layer phone gate (TYPE → COUNTRY → per-number).
• senderName (string)
• senderEmail (string)

Optional cover-page fields (printed only when includeCover is true):

• includeCover (boolean) — free accounts always include a branded cover; paid accounts default to false
• coverNote (string, ≤500) — message body
• recipientName (≤50), subject (≤200), senderCompany (≤100), senderPhone (validated E.164)

Returns: { success, faxId, status, statusUrl }

🔗 faxdrop_pair_number

Add a fax number to the paired whitelist (~/.faxdrop-mcp/paired.json). Only effective when FAXDROP_MCP_NUMBER_GATE=pairing (default). The number must still pass the TYPE and COUNTRY checks (no bypass). Always confirm with the user before pairing — paired numbers can be faxed without further per-number approval.

Required:

• recipientNumber (string) — E.164

Returns: { paired, country, type }

📊 faxdrop_get_fax_status

Check the delivery status of a previously sent fax. Terminal statuses (delivered / failed / partial) are cached process-wide (LRU 100 entries, whitelist-sliced) — re-polling a finished fax short-circuits with a _cached: true marker to spare your FaxDrop quota.

Recommended polling cadence: every ~5s for the first 2 min, then every ~30s for up to 10 min, stop on terminal status.

Required:

• faxId (string)

Returns: { id, status, recipientNumber?, pages?, completedAt?, _cached? }

🛡️ Safeguards

| Knob | Env var | Default | Notes | |---|---|---|---| | Outbox jail | FAXDROP_MCP_WORK_DIR=/abs/path | ~/FaxOutbox/ (auto-created mode 0o700) | Every filePath must live inside this directory after realpath canonicalization. Symlinks to outside the outbox are rejected. | | Number gate | FAXDROP_MCP_NUMBER_GATE=open\|pairing\|closed | pairing | pairing requires HITL approval via faxdrop_pair_number before a new number can be faxed. closed disables runtime pairing (paired.json edited out-of-band). | | Allowed types | FAXDROP_MCP_ALLOWED_TYPES=... | FIXED_LINE,FIXED_LINE_OR_MOBILE,VOIP,TOLL_FREE | libphonenumber NumberType allow-list. | | Allowed countries | FAXDROP_MCP_ALLOWED_COUNTRIES=... | US,CA,PR,GU,VI,AS,MP | ISO-3166-1 alpha-2 allow-list (US/CA + US territories). | | State directory | FAXDROP_MCP_STATE_DIR=/abs/path | ~/.faxdrop-mcp/ (mode 0o700) | Where paired.json lives (mode 0o600, atomic write). | | Dry run | FAXDROP_MCP_DRY_RUN=true | off | Write tools (faxdrop_send_fax, faxdrop_pair_number) return the would-be payload (passed through the same allowlist redaction as the audit log — see row below) and never call FaxDrop or touch paired.json. | | Audit log | FAXDROP_MCP_AUDIT_LOG=/abs/path/audit.log | off | Append-only JSON Lines (file mode 0o600). Allowlist-based redaction: only FaxDrop response-shape fields (recipientNumber, faxId, id) are kept in clear; known credential keys (apiKey / authorization / password / secret / token) are replaced with [REDACTED]; every other field is elided with a [ELIDED:NNN] length marker. This is a fail-closed design: a new API field added upstream is hidden by default, not leaked. |

⚠️ Error catalog

Every failure is returned as isError: true with a structured error_type, message, and (when applicable) hint and retry_after. Programmatic consumers can match on error_type (in structuredContent) to drive retry logic.

| error_type | Layer | Trigger | Suggested action | |---|---|---|---| | phone_parse | input | Recipient number can't be parsed by libphonenumber. | Ask user for an E.164 number. | | phone_type | policy | Phone type (e.g. MOBILE) not in FAXDROP_MCP_ALLOWED_TYPES. | Use a fax line, or extend the env var. | | phone_country | policy | Country not in FAXDROP_MCP_ALLOWED_COUNTRIES. | Confirm with the user; extend the env var if intentional. | | phone_gate | policy | Number not in paired.json and gate is pairing or closed. | In pairing mode: call faxdrop_pair_number first. In closed: edit paired.json out-of-band. | | pair_disabled | policy | faxdrop_pair_number called outside pairing mode. | Set FAXDROP_MCP_NUMBER_GATE=pairing. | | bad_request | filesystem | Path is relative, outside outbox, leaf-symlink, missing, oversized, or has an unsupported extension. | The accompanying hint describes the exact remedy. | | unauthorized | upstream | FaxDrop returned 401. | Check FAXDROP_API_KEY in your MCP client config. | | payment_required | upstream | FaxDrop returned 402 (out of credits). | Top up at the FaxDrop pricing page. | | rate_limited | upstream | FaxDrop returned 429. | Wait retry_after seconds; the hint shows the bucket that was hit. | | invalid_response | upstream | FaxDrop returned a non-JSON body (proxy interception, incident page). | Body is discarded for safety; check FaxDrop status page. | | fax_error | upstream (fallback) | FaxDrop returned an error with no error_type field. | Read the message; treat as transient. |

🚦 Rate limits & quotas

Two independent caps gate every fax send, both enforced by FaxDrop:

• Per-key rate limits (per-minute / per-hour / per-day buckets) — 429 rate_limited with retry_after and X-RateLimit-* headers.
• Account credit balance — 402 payment_required when you run out, with a top-up hint.

The MCP does not add its own limiter; it forwards FaxDrop's response as a clean isError: true with error_type, hint, and retry_after. See FaxDrop's API docs for the current numbers.

🔒 Security

• Always confirm with the user (recipient, file, cover-page) before invoking faxdrop_send_fax. This is also baked into the tool description.
• The MCP reads files from the user's local filesystem — only expose this server to agents you trust.
• Test prompts safely with FAXDROP_MCP_DRY_RUN=true.
• See SECURITY.md for the vulnerability reporting process.

🗺️ Roadmap

See ROADMAP.md.

🌐 Ecosystem

Other MCP servers in the klodr family:

• 📧 klodr/gmail-mcp — Gmail
• 📠 klodr/faxdrop-mcp — Send real faxes via FaxDrop (you are here)
• 🏦 klodr/mercury-invoicing-mcp — Mercury banking + invoicing

🤝 Contributing

PRs welcome. See CONTRIBUTING.md for the test/build/lint checklist and release process.

📄 License

MIT — see LICENSE.