dropscan-mcp

dropscan-mcp

Dropscan の郵便物からメールへの変換 API 用 MCP（Model Context Protocol）サーバーです。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])