Skip to main content
Glama
klodr

faxdrop-mcp

by klodr

πŸ“  faxdrop-mcp

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

CI CodeQL Tested with Vitest codecov OpenSSF Scorecard OpenSSF Best Practices Socket Security CodeRabbit Pull Request Reviews

npm version npm downloads Node.js Version MCP MCP Server PRs Welcome

Sponsor on GitHub Patreon Ko-fi

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.

Related MCP server: verifox-mcp

πŸ“¦ 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)

Notifications:

  • sendEmail (boolean) β€” whether FaxDrop should email the sender a per-fax delivery confirmation. Defaults to false (suppress) β€” the MCP is built for batch/agent workflows where one email per fax floods the inbox, and the same information is already retrievable via faxdrop_get_fax_status. Set to true to opt back in. Failed-fax emails, operator alerts, refunds and status pages are unaffected. The send response echoes deliveryEmail: 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

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:

🀝 Contributing

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

πŸ“„ License

MIT β€” see LICENSE.

Available Tools

3 tools
faxdrop_get_fax_statusA
Read-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.

ParametersJSON Schema
NameRequiredDescriptionDefault
faxIdYesThe fax ID returned by faxdrop_send_fax (e.g. fax_abc123).

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses side effects (API hit, rate limits, caching), terminal statuses, and aligns with annotations (readOnlyHint, openWorldHint). No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise yet thorough, with clear sections (USE WHEN, DO NOT USE, SIDE EFFECTS, POLLING STRATEGY). No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Without output schema, description explains return values (status object + _cached flag). Covers all necessary context for a polling tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of params; description adds context that faxId comes from faxdrop_send_fax, aiding correct usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Check the delivery status of a previously sent fax.' It distinguishes from siblings by specifying it polls for faxes sent via faxdrop_send_fax.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides when to use (polling for fax sent via this MCP), when not to use (faxes sent outside), and includes a detailed polling strategy.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

faxdrop_pair_numberA
Idempotent

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 }.

ParametersJSON Schema
NameRequiredDescriptionDefault
recipientNumberYesRecipient fax number, international (E.164) format with leading + and country code, e.g. +12125551234

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations (destructiveHint=false, idempotentHint=true, openWorldHint=true) are consistent. The description adds valuable behavioral context: it writes to a persistent file, requires user confirmation, and notes that validation still applies. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured with clear sections (USE WHEN, DO NOT USE, SIDE EFFECTS, VALIDATION, RETURNS). Every sentence adds value, and the total length is appropriate for the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description explicitly states the return format ({ paired, country, type }). It covers side effects, persistence, user confirmation, and validation. Annotations and one parameter make this a well-rounded description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage for the single parameter (recipientNumber), describing E.164 format. The description adds meaning by explaining that validation checks (type, country) still apply at pairing time, which goes beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Add a fax number to the per-recipient whitelist (paired.json).' It distinguishes itself from siblings (faxdrop_get_fax_status and faxdrop_send_fax) by specifying that it is for pre-approving recurring recipients to skip confirmation in faxdrop_send_fax.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly gives when to use ('server runs with FAXDROP_MCP_NUMBER_GATE=pairing and the user wants to pre-approve a recurring recipient'), when not to use ('gate mode is open or closed'), and an alternative ('For one-off faxes, skip pairing and call faxdrop_send_fax directly').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

faxdrop_send_faxA
Destructive

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
subjectNoCover page subject / RE: line (max 200 chars).
filePathYesAbsolute path to the document to fax (PDF, DOCX, JPEG, or PNG, ≀10MB).
coverNoteNoMessage printed on the cover page (max 500 chars). Only used when includeCover is true.
sendEmailNoWhether FaxDrop should email the sender a per-fax delivery confirmation. Defaults to **false** (suppress) β€” the MCP is built for batch / agent workflows where one email per fax floods the inbox, and the same information is already available via `faxdrop_get_fax_status`. Set to true to opt back into the confirmation email. Failed-fax emails, operator alerts, refunds and status pages are unaffected. The send response echoes `deliveryEmail: enabled | suppressed`.
senderNameYesSender display name shown on the cover page.
senderEmailYesSender email for delivery confirmation.
senderPhoneNoSender callback number shown on the cover page (E.164 format).
includeCoverNoInclude a FaxDrop cover page. Free accounts always include a branded cover regardless; paid accounts default to false. The cover-page fields below (coverNote, recipientName, subject, senderCompany, senderPhone) are only printed when includeCover is true.
recipientNameNoRecipient display name on the cover page, e.g. "Dr. Jane Smith" (max 50 chars).
senderCompanyNoSender company shown on the cover page (max 100 chars).
recipientNumberYesRecipient fax number, international (E.164) format with leading + and country code, e.g. +12125551234

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description adds significant context beyond annotations (destructiveHint, openWorldHint): charges, audit log, fax ID allocation, file location restrictions, and cover page behavior for free accounts. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with headings and bullet points. Front-loaded with purpose and usage. Every sentence earns its place; no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers side effects, return value structure, polling via sibling tool, file location prerequisites, and parameter interdependencies. Complete for a complex tool with 11 parameters and no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers all 11 parameters with descriptions (100% coverage). Description adds value by explaining file path requirements and cover page interactions (free accounts always include branded cover). Enhances understanding but schema already strong.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Send a real fax via FaxDrop' with specific verb and resource. It distinguishes from sibling tools (faxdrop_pair_number, faxdrop_get_fax_status) by focusing on the act of sending a fax.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'USE WHEN' and 'DO NOT USE' sections provide clear conditions for use. Lists alternatives (email, sftp) and advises user confirmation steps. Very actionable guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.10.0
    • Changedfaxdrop_send_fax1 field changed
      • addedInput schema / properties / sendEmail
        Added value: +{
        +  "default": false,
        +  "description": "Whether FaxDrop should email the sender a per-fax delivery confirmation. Defaults to **false** (suppress) β€” the MCP is built for batch / agent workflows where one email per fax floods the inbox, and the same information is already available via `faxdrop_get_fax_status`. Set to true to opt back into the confirmation email. Failed-fax emails, operator alerts, refunds and status pages are unaffected. The send response echoes `deliveryEmail: enabled | suppressed`.",
        +  "type": "boolean"
        +}
  2. 3 tool updatesv0.8.7
    • Addedfaxdrop_get_fax_status
    • Addedfaxdrop_pair_number
    • Addedfaxdrop_send_fax
  3. 3 tool updatesv0.8.5
    • Removedfaxdrop_get_fax_status
    • Removedfaxdrop_pair_number
    • Removedfaxdrop_send_fax
  4. 3 tool updatesv0.8.4
    • Addedfaxdrop_get_fax_status
    • Addedfaxdrop_pair_number
    • Addedfaxdrop_send_fax
  5. 3 tool updatesv0.8.2
    • Removedfaxdrop_get_fax_status
    • Removedfaxdrop_pair_number
    • Removedfaxdrop_send_fax
  6. 3 tool updates
    • First observedfaxdrop_get_fax_status
    • First observedfaxdrop_pair_number
    • First observedfaxdrop_send_fax

TDQS

A4.8/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a distinct purpose: sending, whitelisting, and status checking. No overlap or ambiguity.

Naming Consistency5/5

All tools follow a consistent pattern of 'faxdrop_verb_noun' with snake_case naming, making the set predictable.

Tool Count4/5

With 3 tools, the server covers core fax operations without unnecessary bloat. While minimal, it suits a focused MCP server.

Completeness4/5

Essential operations (send, whitelist, status) are covered. A cancel or list tool would improve completeness, but the current set handles primary use cases.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    B
    maintenance
    Enables AI assistants to verify email deliverability and find business emails via the Verifox API, supporting single and bulk operations.
    6
    82 npm
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables 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