Skip to main content
Glama
dropscan-mcp

dropscan-mcp

by bitterdev

dropscan-mcp

MCP (Model Context Protocol) server for the Dropscan postal-mail-to-email API. Dropscan receives your physical letters at a scanbox; this server lets your MCP client list mailings, download the scans (PDF / ZIP / envelope image / OCR text), and, when explicitly enabled, request actions (scan / forward / destroy) and manage recipients, forwarding addresses and webhook rules.

mcp-name: io.github.bitterdev/dropscan-mcp

Safety first: Dropscan has no sandbox

Every request hits the real production account. Actions are irreversible: a destroyed letter is physically shredded and gone, a forward physically mails the letter and costs money.

Because of that, all write/action tools are gated twice:

  1. DROPSCAN_ALLOW_WRITES environment flag. Unless it is set to 1/true/yes, every non-GET tool refuses to run. It is disabled by default.

  2. confirm: true parameter. Each write/action tool takes an explicit confirm argument (default false) and refuses unless it is true.

Read-only GET tools are always available and never change state.

Related MCP server: guerrillamail-mcp

Tools

Read-only (always available)

Tool

Endpoint

list_scanboxes

GET /scanboxes

list_mailings(scanbox_id, current_status?, older_than?)

GET /scanboxes/{id}/mailings

get_mailing(scanbox_id, uuid)

GET /scanboxes/{id}/mailings/{uuid}

get_mailing_pdf(scanbox_id, uuid, save_path?)

GET .../{uuid}/pdf

get_mailing_zip(scanbox_id, uuid, save_path?)

GET .../{uuid}/zip

get_mailing_envelope(scanbox_id, uuid, save_path?)

GET .../{uuid}/envelope

get_mailing_plaintext(scanbox_id, uuid)

GET .../{uuid}/plaintext

list_recipients(scanbox_id)

GET /scanboxes/{id}/recipients

get_recipient(scanbox_id, recipient_id)

GET /scanboxes/{id}/recipients/{id}

get_forwarding_address(address_id)

GET /forwarding_addresses/{id}

get_shipment(shipment_id)

GET /shipments/{id}

list_webhook_rules()

GET /webhook_rules

get_webhook_rule(rule_id)

GET /webhook_rules/{id}

The download tools save the asset to disk (default ~/Downloads, override with save_path or the DROPSCAN_DOWNLOAD_DIR env var) and return the saved path, byte size and content type.

Write / action (double-gated: DROPSCAN_ALLOW_WRITES=1 and confirm=true)

Tool

Endpoint

request_mailing_action(scanbox_id, mailing_uuid, action_type, forwarding_address_id?, forwarding_date?, confirm)

POST .../{uuid}/action_requests

cancel_mailing_action(scanbox_id, mailing_uuid, action_request_id, confirm)

DELETE .../{uuid}/action_requests/{id}

set_mailing_recipient(scanbox_id, mailing_uuid, recipient_id, confirm)

PUT .../{uuid}/recipient

create_recipient(scanbox_id, type, firstname?, lastname?, name?, confirm)

POST /scanboxes/{id}/recipients

create_forwarding_address(firstname, lastname, street, number, zip_code, city, country_code, company?, info?, state?, confirm)

POST /forwarding_addresses

create_webhook_rule(url, events, authorization_header?, confirm)

POST /webhook_rules

update_webhook_rule(rule_id, url?, events?, authorization_header?, confirm)

PATCH /webhook_rules/{id}

delete_webhook_rule(rule_id, confirm)

DELETE /webhook_rules/{id}

action_type is one of scan, forward, destroy (exact enum from the API). For forward, both forwarding_address_id and forwarding_date (ISO YYYY-MM-DD) are required.

Webhook events: mailing_received, scan_requested, mailing_scanned, mailing_archived, mailing_trashed, mailing_shredded, mailing_added_to_shipment, mailing_removed_from_shipment, shipment_sent, package_tracking_updated.

Requirements

  • Python >= 3.10

  • A Dropscan personal access token

Installation

From a local clone:

python3 -m venv .venv
./.venv/bin/pip install .

Configuration

The token is read from the DROPSCAN_TOKEN environment variable and sent as Authorization: Bearer <token>. It is never hardcoded.

Claude Code

claude mcp add dropscan -e DROPSCAN_TOKEN="dspat-..." -- dropscan-mcp

Claude Desktop / generic MCP client

{
  "mcpServers": {
    "dropscan": {
      "command": "/absolute/path/to/dropscan-mcp/.venv/bin/python",
      "args": ["-m", "dropscan_mcp.server"],
      "env": {
        "DROPSCAN_TOKEN": "dspat-..."
      }
    }
  }
}

To enable the write/action tools, add "DROPSCAN_ALLOW_WRITES": "1" to env. Leave it out to keep the server strictly read-only.

The server runs over stdio.

Environment variables

Variable

Description

DROPSCAN_TOKEN

Required. Dropscan personal access token (Bearer).

DROPSCAN_ALLOW_WRITES

Set to 1/true to enable write/action tools. Default: disabled.

DROPSCAN_DOWNLOAD_DIR

Default directory for downloaded PDFs/ZIPs/images. Default: ~/Downloads.

License

MIT, see LICENSE.

Author

Fabian Bitter (fabian@bitter.de)

Available Tools

21 tools
cancel_mailing_actionA

Cancel a pending action request on a mailing.

⚠️ Changes the real production account. Cancellation windows apply (scan: 10 min, destroy: 60 min, forward: before the requested date, Berlin time). Double-gated: requires DROPSCAN_ALLOW_WRITES=1 AND confirm=true.

DELETE /scanboxes/{scanbox_id}/mailings/{mailing_uuid}/action_requests/{id}

Inputs: scanbox_id (required), mailing_uuid (required), action_request_id (required), confirm.

create_forwarding_addressA

Create a forwarding address (used as a forward target).

⚠️ Changes the real production account. Double-gated: requires DROPSCAN_ALLOW_WRITES=1 AND confirm=true.

POST /forwarding_addresses

Args: country_code: 2-3 char ISO country code (e.g. "DE"). zip_code: Postal code (sent as "zip" in the request body).

Inputs: city (required), number (required), street (required), lastname (required), +7 more.

create_recipientA

Create a recipient on a scanbox.

⚠️ Changes the real production account. Double-gated: requires DROPSCAN_ALLOW_WRITES=1 AND confirm=true.

POST /scanboxes/{scanbox_id}/recipients

Args: type: "Person" or "Company". firstname, lastname: Required when type="Person". name: Required when type="Company".

Inputs: type (required), scanbox_id (required), name, confirm, +2 more.

create_webhook_ruleA

Create a webhook rule.

⚠️ Changes the real production account. Double-gated: requires DROPSCAN_ALLOW_WRITES=1 AND confirm=true.

POST /webhook_rules

Args: events: One or more of: mailing_received, scan_requested, mailing_scanned, mailing_archived, mailing_trashed, mailing_shredded, mailing_added_to_shipment, mailing_removed_from_shipment, shipment_sent, package_tracking_updated.

Inputs: url (required), events (required), confirm, authorization_header.

delete_webhook_ruleA

Delete a webhook rule.

⚠️ Changes the real production account and cannot be undone. Double-gated: requires DROPSCAN_ALLOW_WRITES=1 AND confirm=true.

DELETE /webhook_rules/{id}

Inputs: rule_id (required), confirm.

get_forwarding_addressC

Get a forwarding address by id. Read-only.

GET /forwarding_addresses/{id}

Inputs: address_id (required).

get_mailingA

Get one mailing with its details/extracted content. Read-only.

GET /scanboxes/{scanbox_id}/mailings/{uuid}

Inputs: uuid (required), scanbox_id (required).

get_mailing_envelopeB

Download a mailing's envelope image (JPEG) and save it. Read-only.

GET /scanboxes/{scanbox_id}/mailings/{uuid}/envelope

Inputs: uuid (required), scanbox_id (required), save_path.

get_mailing_pdfB

Download a mailing's scanned PDF and save it to disk. Read-only.

GET /scanboxes/{scanbox_id}/mailings/{uuid}/pdf

Args: save_path: Absolute path to write the PDF to. Defaults to ~/Downloads/dropscan-.pdf (or DROPSCAN_DOWNLOAD_DIR).

Inputs: uuid (required), scanbox_id (required), save_path.

get_mailing_plaintextB

Get OCR plaintext of a mailing (first 5 documents). Read-only.

GET /scanboxes/{scanbox_id}/mailings/{uuid}/plaintext

Inputs: uuid (required), scanbox_id (required).

get_mailing_zipB

Download a mailing's ZIP (individual PDFs) and save it. Read-only.

GET /scanboxes/{scanbox_id}/mailings/{uuid}/zip

Inputs: uuid (required), scanbox_id (required), save_path.

get_recipientC

Get one recipient of a scanbox. Read-only.

GET /scanboxes/{scanbox_id}/recipients/{id}

Inputs: scanbox_id (required), recipient_id (required).

get_shipmentB

Get a shipment (physical forwarding batch) by id. Read-only.

GET /shipments/{id}

Inputs: shipment_id (required).

get_webhook_ruleB

Get one webhook rule by id. Read-only.

GET /webhook_rules/{id}

Inputs: rule_id (required).

list_mailingsA

List mailings in a scanbox (GET /scanboxes/{id}/mailings). Read-only.

Args: scanbox_id: Scanbox id (e.g. "12345"). current_status: Optional status filter. One of: received, scan_requested, scanned, destroy_requested, destroyed, forward_requested, forwarded. older_than: Optional mailing UUID cursor for pagination; returns mailings older than the given one.

Inputs: scanbox_id (required), older_than, current_status.

list_recipientsB

List recipients configured for a scanbox. Read-only.

GET /scanboxes/{scanbox_id}/recipients

Inputs: scanbox_id (required).

list_scanboxesA

List all scanboxes on the account (GET /scanboxes). Read-only.

Inputs: no named parameters.

list_webhook_rulesA

List all webhook rules on the account. Read-only.

GET /webhook_rules

Inputs: no named parameters.

request_mailing_actionA

Request a physical action on a mailing (scan / forward / destroy).

⚠️ AFFECTS THE REAL PRODUCTION ACCOUNT AND CANNOT BE UNDONE. "destroy" physically shreds the letter, it is gone for good. "forward" physically mails the letter to an address and incurs cost. Double-gated: requires DROPSCAN_ALLOW_WRITES=1 AND confirm=true.

POST /scanboxes/{scanbox_id}/mailings/{mailing_uuid}/action_requests

Args: action_type: One of "scan", "forward", "destroy". forwarding_address_id: Required when action_type="forward"; the id of a forwarding address (see create_forwarding_address / get_forwarding_address). forwarding_date: Required when action_type="forward"; ISO date (YYYY-MM-DD). confirm: Must be True to proceed.

Inputs: scanbox_id (required), action_type (required), mailing_uuid (required), confirm, +2 more.

set_mailing_recipientB

Assign a recipient to a mailing.

⚠️ Changes the real production account. Double-gated: requires DROPSCAN_ALLOW_WRITES=1 AND confirm=true.

PUT /scanboxes/{scanbox_id}/mailings/{mailing_uuid}/recipient

Inputs: scanbox_id (required), mailing_uuid (required), recipient_id (required), confirm.

update_webhook_ruleA

Update a webhook rule.

⚠️ Changes the real production account. Double-gated: requires DROPSCAN_ALLOW_WRITES=1 AND confirm=true.

PATCH /webhook_rules/{id}

Inputs: rule_id (required), url, events, confirm, +1 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 21 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action, with clear boundaries between scanboxes, mailings, recipients, forwarding addresses, webhook rules, and shipments. No overlapping purposes.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case, making the set predictable and easy to navigate.

    Tool Count4/5

    21 tools is slightly high but justified by the multi-entity domain (scanboxes, mailings, recipients, etc.). Each tool serves a specific purpose, though a few could be merged or removed.

    Completeness4/5

    Core CRUD operations are covered for most entities, but missing delete/update for recipients and forwarding addresses. The essential workflows (receive, scan, forward, destroy, manage webhooks) are well-supported.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Official mailbox.bot MCP server for AI agents. Send letters, certified mail and postcards, and give an agent its own street address + postal mailbox number. Agent receiving virtual mailboxes with a real street address are live now at $15/mo in Manhattan Beach, CA. Sandbox keys, approval controls, tracking and webhooks.
      55
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for the Guerrilla Mail temporary/disposable email API. Spin up throwaway inboxes, poll for mail, and read messages from any MCP client.
      6
      14 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A minimal MCP server for reading, searching, managing, and sending email over IMAP and SMTP.
      MIT