dropscan-mcp

dropscan-mcp

用于 Dropscan 邮件转电子邮件 API 的 MCP（模型上下文协议）服务。Dropscan 会在扫描箱中接收您的纸质信件；此服务可让您的 MCP 客户端列出邮件、下载扫描件（PDF / ZIP / 信封图像 / OCR 文本），并在明确启用后请求操作（扫描 / 转寄 / 销毁）以及管理收件人、转寄地址和 webhook 规则。

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

安全第一：Dropscan 没有沙盒

每个请求都会访问真实的生产账户。操作不可撤销：信件一旦销毁，就会被实际粉碎并永久消失；转寄会实际邮寄信件并产生费用。

因此，所有写入 / 操作工具都需要通过双重门控：

1. DROPSCAN_ALLOW_WRITES 环境标志。除非设置为 1/true/yes，否则所有非 GET 工具都拒绝运行。此标志默认禁用。
2. confirm: true 参数。每个写入 / 操作工具都需要一个显式的 confirm 参数（默认为 false），且除非该参数为 true，否则会拒绝运行。

只读 GET 工具始终可用，且不会更改状态。

工具

只读（始终可用）

工具	端点
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}

下载工具会将资源保存到磁盘（默认保存到 ~/Downloads；可通过 save_path 或 DROPSCAN_DOWNLOAD_DIR 环境变量覆盖），并返回保存路径、字节大小和内容类型。

写入 / 操作（双重门控：DROPSCAN_ALLOW_WRITES=1 且 confirm=true）

工具	端点
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 可取 scan、forward、destroy 之一（与 API 中的枚举值完全一致）。对于 forward，必须同时提供 forwarding_address_id 和 forwarding_date（ISO 格式 YYYY-MM-DD）。

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。

要求

• Python >= 3.10
• Dropscan 个人访问令牌

安装

从本地克隆开始：

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

配置

令牌从 DROPSCAN_TOKEN 环境变量读取，并以 Authorization: Bearer <token> 的形式发送。它绝不会被硬编码。

Claude Code

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

Claude Desktop / 通用 MCP 客户端

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

要启用写入/操作工具，请在 env 中添加 "DROPSCAN_ALLOW_WRITES": "1"。不添加此项即可让服务保持严格只读。

服务通过 stdio 运行。

环境变量

变量	描述
DROPSCAN_TOKEN	必需。 Dropscan 个人访问令牌（Bearer）。
DROPSCAN_ALLOW_WRITES	设置为 1/true 以启用写入/操作工具。默认：禁用。
DROPSCAN_DOWNLOAD_DIR	下载的 PDF/ZIP/图片的默认目录。默认：~/Downloads。

许可证

MIT，详见 LICENSE。

作者

Fabian Bitter ([email protected])