dropscan-mcp
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., "@dropscan-mcp list my recent mailings"
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.
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_WRITESenvironment flag. Unless it is set to1/true/yes, every non-GET tool refuses to run. It is disabled by default.confirm: trueparameter. Each write/action tool takes an explicitconfirmargument (defaultfalse) and refuses unless it istrue.
Read-only GET tools are always available and never change state.
Related MCP server: guerrillamail-mcp
Tools
Read-only (always available)
Tool | Endpoint |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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-mcpClaude 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 |
| Required. Dropscan personal access token (Bearer). |
| Set to |
| Default directory for downloaded PDFs/ZIPs/images. Default: |
License
MIT, see LICENSE.
Author
Fabian Bitter (fabian@bitter.de)
Available Tools
21 toolscancel_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
Scored across 21 tools
Each tool targets a distinct resource and action, with clear boundaries between scanboxes, mailings, recipients, forwarding addresses, webhook rules, and shipments. No overlapping purposes.
All tool names follow a consistent verb_noun pattern in snake_case, making the set predictable and easy to navigate.
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.
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
Related MCP Connectors
The first MCP server for physical mail: send postcards and letters, manage lists and campaigns.
Your mailbox for MCP clients: search, read, draft, send, rules and notes. Sending is off by default.
Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.
MCP server for MailTempo's public free temporary email inboxes.
Related MCP Servers
- AlicenseBqualityBmaintenanceOfficial 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.552MIT
- AlicenseAqualityCmaintenanceMCP server for the Guerrilla Mail temporary/disposable email API. Spin up throwaway inboxes, poll for mail, and read messages from any MCP client.614 npm1MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for accessing Czech datové schránky (ISDS) with legal semantics. Enables AI agents to safely read, send, and archive messages while respecting delivery triggers and deadlines.3MIT
- AlicenseNot gradedqualityDmaintenanceA minimal MCP server for reading, searching, managing, and sending email over IMAP and SMTP.MIT