faxdrop-mcp
An MCP server that lets an AI assistant send real faxes through the FaxDrop HTTP API, with recipient pairing and delivery-status polling.
faxdrop_send_fax— fax a local document (PDF, DOCX, JPEG, PNG, ≤10 MB) from the outbox (~/FaxOutbox/, overridable) to an E.164 number; optional cover page (note ≤500, recipient name, subject, company, callback phone) and opt-in per-fax confirmation email (suppressed by default). Charges FaxDrop credits.faxdrop_pair_number— add a recurring recipient to thepaired.jsonwhitelist so future sends skip per-number approval; TYPE and COUNTRY checks still apply (no bypass).faxdrop_get_fax_status— poll a previously sent fax (queued/sending/completed/failed/partial), with terminal results cached process-wide to save quota.Built-in safeguards — outbox path jail, 3-layer phone gate (TYPE → COUNTRY → pairing), dry-run mode, allowlist-redacted JSONL audit log, and structured
error_type/hint/retry_aftererrors for retry logic.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@faxdrop-mcp send a fax to +12125551234 with the contract.pdf file"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
📠 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=trueto test prompts without sending;FAXDROP_MCP_AUDIT_LOG=/abs/pathfor a JSONL trail (mode0o600).Clean errors — FaxDrop's 402 / 429 / 4xx surfaced as MCP
isErrorwitherror_type,hint,retry_after.Drop-in for any MCP client — one
npx -y faxdrop-mcpline 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.
Related MCP server: GotFreeFax MCP Server
📦 Installation
npm install -g faxdrop-mcpOr 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 falsecoverNote(string, ≤500) — message bodyrecipientName(≤50),subject(≤200),senderCompany(≤100),senderPhone(validated E.164)
Notifications:
sendEmail(boolean) — whether FaxDrop should email the sender a per-fax delivery confirmation. Defaults tofalse(suppress) — the MCP is built for batch/agent workflows where one email per fax floods the inbox, and the same information is already retrievable viafaxdrop_get_fax_status. Set totrueto opt back in. Failed-fax emails, operator alerts, refunds and status pages are unaffected. The send response echoesdeliveryEmail: enabled | suppressed.
Returns: { success, faxId, status, statusUrl, deliveryEmail }
🔗 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 |
|
| Every |
Number gate |
|
|
|
Allowed types |
|
| libphonenumber |
Allowed countries |
|
| ISO-3166-1 alpha-2 allow-list (US/CA + US territories). |
State directory |
|
| Where |
Dry run |
| off | Write tools ( |
Audit log |
| off | Append-only JSON Lines (file mode |
⚠️ 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.
| Layer | Trigger | Suggested action |
| input | Recipient number can't be parsed by libphonenumber. | Ask user for an E.164 number. |
| policy | Phone type (e.g. MOBILE) not in | Use a fax line, or extend the env var. |
| policy | Country not in | Confirm with the user; extend the env var if intentional. |
| policy | Number not in | In |
| policy |
| Set |
| filesystem | Path is relative, outside outbox, leaf-symlink, missing, oversized, or has an unsupported extension. | The accompanying |
| upstream | FaxDrop returned 401. | Check |
| upstream | FaxDrop returned 402 (out of credits). | Top up at the FaxDrop pricing page. |
| upstream | FaxDrop returned 429. | Wait |
| upstream | FaxDrop returned a non-JSON body (proxy interception, incident page). | Body is discarded for safety; check FaxDrop status page. |
| upstream (fallback) | FaxDrop returned an error with no | 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_limitedwithretry_afterandX-RateLimit-*headers.Account credit balance —
402 payment_requiredwhen 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.Behind a local proxy that answers DNS itself (Surge in enhanced mode hands out
198.18.0.0/15), setMCP_TRUSTED_CIDRS=198.18.0.0/15so the SSRF guard accepts its addresses; prefer a single IP whenever the proxy allows it. Refused at startup: a malformed entry, more than 131,072 addresses in all (one range: IPv4/15at most, IPv6/111), anything that touches loopback, link-local,0.0.0.0/8or an IPv6 range carrying an IPv4 (an IPv4-mapped address such as::ffff:10.47.83.1counts as its IPv4).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.
Available Tools
3 toolsfaxdrop_get_fax_statusARead-only
Check the delivery status of a previously sent fax.
USE WHEN: polling for the outcome of a fax sent via faxdrop_send_fax. Status values: queued | sending | completed (or legacy delivered) | failed | partial.
DO NOT USE: for faxes sent outside this MCP (no provenance — server returns 404). Once status is completed (or delivered), failed, or partial, STOP polling — these are terminal.
SIDE EFFECTS: each non-cached call hits the FaxDrop API and counts toward its per-key rate limits (no monetary cost). Terminal results are cached process-wide.
POLLING STRATEGY: every ~5s for the first 2 min, then every ~30s up to 10 min. Most US faxes complete in <90s.
RETURNS: provider status object + optional _cached: true flag.
Inputs: faxId (required).
faxdrop_pair_numberAIdempotent
Add a fax number to the per-recipient whitelist (paired.json).
USE WHEN: server runs with FAXDROP_MCP_NUMBER_GATE=pairing and the user wants to pre-approve a recurring recipient (clinic, lawyer, supplier) so future faxdrop_send_fax calls skip the per-number confirmation step.
DO NOT USE: when gate mode is open (no whitelist needed) or closed (whitelist edited out-of-band only — pairing rejected). For one-off faxes, skip pairing and call faxdrop_send_fax directly.
SIDE EFFECTS: writes to ~/.faxdrop-mcp/paired.json (or $FAXDROP_MCP_STATE_DIR/paired.json). Persistent across runs. ALWAYS confirm with the user — paired numbers can be faxed without further per-number approval.
VALIDATION: TYPE + COUNTRY checks still apply (no bypass). Mobile/landline/premium numbers are rejected even at pairing time.
RETURNS: { paired, country, type }.
Inputs: recipientNumber (required).
faxdrop_send_faxADestructive
Send a real fax via FaxDrop.
USE WHEN: user needs to fax a document (PDF, DOCX, JPEG, PNG ≤10MB) to a fax number — medical records, legal forms, government submissions, recipients who only accept fax.
DO NOT USE: for digital delivery (email, sftp), for files outside the outbox, for non-fax numbers — the 3-layer phone gate (TYPE → COUNTRY → per-number policy) rejects mobile/landline/premium.
SIDE EFFECTS: charges FaxDrop balance (or consumes free credits + adds branded cover on free tier), creates an audit log entry, allocates a fax ID server-side. ALWAYS confirm recipient + file + cover with the user before calling.
FILE LOCATION: document must live inside the outbox (default ~/FaxOutbox/, override via FAXDROP_MCP_WORK_DIR). Files outside are rejected — ask the user to copy in first.
RETURNS: { faxId, status: "queued", ... } — poll with faxdrop_get_fax_status.
Inputs: filePath (required), senderName (required), senderEmail (required), recipientNumber (required), +7 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
The three tools target clearly distinct actions: sending (faxdrop_send_fax), checking outcome (faxdrop_get_fax_status), and pre-approving a recipient (faxdrop_pair_number). Descriptions explicitly cross-reference each other and warn when *not* to use a tool, leaving no realistic misselection path.
All names use the same faxdrop_<verb>_<object> snake_case pattern (send_fax, get_fax_status, pair_number). No mixed conventions or vague verbs.
Three tools is exactly the surface needed for a narrow fax-sending domain: send, poll, and whitelist. Each earns its place and there is no padding.
Core lifecycle (send → poll to terminal state) plus recipient pre-approval is covered. Minor gaps exist in adjacent operations such as cancelling a queued fax, listing sent history, or checking account balance, but agents can work around these.
Maintenance
Related MCP Connectors
Send real faxes from AI assistants: PDF to any fax number, delivery status, pages left.
Send, receive, and verify faxes from AI assistants and agents via FaxSeal.
Send and receive faxes from an AI agent: exact quotes, human approvals, delivery evidence, sandbox.
Send real faxes from AI assistants. Pay per fax ($1 + $0.25/page), no account or API key.
Related MCP Servers
- AlicenseAqualityBmaintenanceMercury Banking MCP server with full Invoicing API support. Read accounts/transactions and create/manage recurring invoices via Model Context Protocol.39246 npm4MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to send free and paid faxes to US and Canada numbers, check fax status, and purchase prepaid credits, all without leaving the chat.MIT
- AlicenseNot gradedqualityDmaintenanceSend, receive, and verify faxes from AI assistants and agents via the Model Context Protocol.59 npmMIT

ictfax-mcpofficial
AlicenseAqualityBmaintenanceEnables AI assistants to list and track fax transmissions, and, when write access is enabled, upload documents and send faxes through ICTFax.246 npm19MIT