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; audit log redacts apiKey/authorization/password/etc. (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 (2)

faxdrop_send_fax

Send a fax. Uploads a local document to a fax number in international (E.164) format.

Required:

• filePath (string, absolute) — PDF, DOCX, JPEG, or PNG, ≤10 MB
• recipientNumber (string) — E.164, e.g. +12125551234
• senderName (string)
• senderEmail (string)

Optional cover-page fields:

• includeCover (boolean) — free accounts default to true; paid accounts default to false
• coverNote (string, ≤500) — message body
• recipientName, subject, senderCompany, senderPhone

Returns: { success, faxId, status, statusUrl }

faxdrop_get_fax_status

Check the delivery status of a previously sent fax.

Required:

• faxId (string) — the ID returned by faxdrop_send_fax

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

Status values: queued | sending | delivered | failed | partial. Most US faxes complete in under 90 seconds.

Safeguards

Knob	Env var	Default	Notes
Dry run	FAXDROP_MCP_DRY_RUN=true	off	Write tools (faxdrop_send_fax) return the would-be payload (sensitive fields redacted) and never call FaxDrop. Reads still pass through.
Audit log	FAXDROP_MCP_AUDIT_LOG=/abs/path/audit.log	off	Append-only JSON Lines (file mode 0o600). Sensitive args are redacted.

Rate limiting is left to FaxDrop itself (10/min, 100/h, 500/day per key). 429 responses get error_type: "rate_limited" and a retry_after value, both surfaced to the caller.

FaxDropError responses are mapped to clean isError: true MCP responses with error_type, hint, and retry_after. HTTP 402 (no credits) and 429 (rate-limited) get explicit hints.

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.

Contributing

PRs welcome. Before submitting:

• npm test (must stay green)
• npm run build (must succeed)
• npm run lint (must succeed)
• CHANGELOG.md updated under [Unreleased]

Releases are automated: bump package.json → merge release PR → git tag -s vX.Y.Z && git push origin vX.Y.Z. The release workflow extracts the matching CHANGELOG section, creates the GitHub Release, signs dist/index.js with Sigstore, and publishes to npm with provenance.

License

MIT — see LICENSE.