Dropscan MCP

एजेंट को Dropscan स्कैन-टू-ईमेल सेवा के माध्यम से आपका भौतिक लेटरबॉक्स देता है, स्कैन किए गए मेल को पढ़ता है और, दोहरे गेट के पीछे, उसे आगे भेजता या नष्ट करता है।

GitHub

दस्तावेज़

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:

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

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)