protonlite

protonlite

Python 製の小型で依存関係の少ない Proton Mail（ProtonMail）向けクライアントおよび API です。Proton Mail Bridge や有料プランなしで、Mail、Calendar、Contacts、Drive を利用できます。エージェント（Claude Code、Cursor）がメールボックスを利用できるよう、オプションの MCP サーバー も付属しています。

Proton には IMAP も SMTP もありません。公式なアクセス方法は Proton Mail Bridge ですが、利用には有料プランが必要です。protonlite は Proton のウェブ API に直接アクセスするため、無料アカウントでも動作します。エンドツーエンド暗号化は Proton 独自の MIT ライセンス Go ライブラリ (go-srp、 go-proton-api) から移植されています。MIT ライセンスを維持し、依存関係も少なく、OpenPGP（メンテナンスされている PGPy のフォークである PGPy13）、bcrypt、requests のみを使用します。CAPTCHA ソルバーもコンピュータービジョンのスタックも不要です。Proton のアプリと同じように、人が Proton の認証ページを完了します。

非公式です。 このプロジェクトは Proton AG とは提携しておらず、Proton の承認やサポートを受けていません。 「Proton」、「Proton Mail」、「Proton Calendar」、「Proton Drive」は Proton AG の商標です。 非公開の未文書化 API にアクセスするため、API はいつでも変更される可能性があり、利用は Proton の利用規約の対象となる場合があります。ご自身の責任で、ご自身が所有するアカウントに対してご利用ください。

できること

• Mail -- 受信トレイや任意のフォルダーの読み取り、メッセージの復号（HTML をテキストに変換）、検索、送信（プレーンテキストまたは HTML、添付ファイル、スレッド内での返信、予約送信）、下書きの保存、既読／未読の切り替え、ゴミ箱への移動／削除、ラベルとフォルダーの管理、ゴミ箱を空にする、ストレージ使用量の確認。
• Calendar -- 予定の確認、イベントの作成／編集／キャンセル、招待状の送信、出欠の返信。
• Contacts -- 署名／暗号化された vCard 形式での連絡先の読み取り、作成、編集、削除。
• Drive -- ファイルの一覧表示、ダウンロード、アップロード（暗号化）、移動、名前の変更、ゴミ箱への移動、公開共有リンクの作成。

すべてエンドツーエンドです。アカウントのパスワードを使ってローカルでキーを解除し、メッセージ、イベント、連絡先、ファイルをお使いのマシン上で復号します。

インストール

pip install protonlite

Python 3.10 以降が必要です。

クイックスタート

import os
import datetime as dt

from protonlite import ProtonMail

# --- Signing in -------------------------------------------------------------
# The recommended way is the CLI `protonlite login`, which reads the password
# with getpass so it never lives in a script. For automation, read it from the
# environment rather than hard-coding it. Proton usually asks a human to
# complete a verification page; login raises HumanVerificationRequired with
# that URL -- open it, then call again passing verification_token (see
# "Signing in" below). Sign in each account once; every login saves its own
# session file.
ProtonMail.login(
    "[email protected]",
    password=os.environ["PROTON_PASSWORD"].encode(),
    session_path="[email protected]",
)

# --- More than one account --------------------------------------------------
# Reopen each saved session independently -- no password needed. The two
# clients are fully independent mailboxes.
client  = ProtonMail.from_session(session_path="[email protected]")    # personal
client1 = ProtonMail.from_session(session_path="[email protected]")   # work
# (after a CLI `protonlite login`, ProtonMail.for_account("work") finds it by name)
print(client.addresses()[0]["Email"], "/", client1.addresses()[0]["Email"])

# --- Mail -------------------------------------------------------------------
for msg in client.list_messages(unread_only=True):
    print(msg.time, msg.sender.address, msg.subject)
full = client.read_message(msg.id)
print(full.text)                                  # HTML flattened to prose
client.send(to=["[email protected]"], subject="Hi", body="Hello")
client1.send(to=["[email protected]"], subject="Hi from work", body="Hello")

# --- Calendar ---------------------------------------------------------------
cal_id = client.list_calendars()[0]["ID"]
begins = dt.datetime.now(dt.timezone.utc) + dt.timedelta(days=1)
event = client.create_event(cal_id, summary="Demo",
                            start=begins, end=begins + dt.timedelta(hours=1))
for ev in client.list_events(cal_id, start=int(begins.timestamp()) - 3600,
                             end=int(begins.timestamp()) + 86400):
    print(dt.datetime.fromtimestamp(ev.start, dt.timezone.utc), ev.title)
client.delete_event(cal_id, event["id"])

# --- Contacts ---------------------------------------------------------------
cid = client.create_contact(name="Ada Lovelace", emails=["[email protected]"])
for row in client.list_contact_emails():
    print(row["name"], row["email"])
client.delete_contacts([cid])

# --- Drive ------------------------------------------------------------------
drive = client.drive()
with open("report.pdf", "rb") as fh:
    drive.upload("", "report.pdf", fh.read(), "application/pdf")
for entry in drive.list_folder(""):
    print(entry["name"], entry["type"])
link = drive.share_link("report.pdf")
print(link["url"])                                # https://drive.proton.me/urls/...#password

コマンドライン

メールの基本操作をカバーする小型の CLI が用意されています。

protonlite login --user [email protected]
protonlite unread
protonlite read <message-id>
protonlite send --to [email protected] --subject "Hi" --body "Hello"

サインイン

サーバーから Proton にログインすると、ほぼ必ず人間による認証ページ（hCaptcha）が表示されます。ログイン処理では、その URL を提示するため、人がブラウザーで認証を完了できます。protonlite は認証を代行せず、ユーザー自身のコード以外の経路でパスワードを求めることもありません。アカウントのパスワードはローカルでキーを導出するためだけに使われ、保存されません。保存されるセッションには、OAuth 形式のトークンと導出されたキーのパスフレーズのみが含まれます。2 要素認証（TOTP）に対応しています。

MCP サーバー

protonlite にはオプションの MCP サーバーが付属しており、任意の MCP クライアント（Cursor、Claude Code、Claude Desktop）から Proton を利用できます。CLI で一度サインインしてから、そのセッションを指定してサーバーを起動します。

pip install "protonlite[mcp]"
protonlite login --user [email protected]          # one-time; saves a session file
PROTONLITE_SESSION=~/[email protected] protonlite-mcp

protonlite mcp でも同じサーバーが起動するため、uvx --from "protonlite[mcp]" protonlite mcp を使えば、ローカルにインストールせずに実行できます（MCP レジストリのエントリーで使われている方法です）。

MCP クライアント（Claude Desktop／Cursor の mcpServers 設定など）に接続します。

{
  "mcpServers": {
    "proton": {
      "command": "protonlite-mcp",
      "env": { "PROTONLITE_SESSION": "/home/you/[email protected]" }
    }
  }
}

サーバーはパスワードを受け取りません。保存されたセッションを再利用します。18 個のツールを公開します。list_messages、read_message、search_messages、send_message、calendar、contacts、Proton Drive 用の一連のツールである drive_list、drive_download、drive_upload、drive_mkdir、drive_move、drive_rename、drive_trash、drive_share_link、drive_unshare_link、および送信ポリシー用の 3 つのツールである email_policy_status、email_allow、set_send_confirmation です。他者のコンテンツは信頼できないデータとしてラップして返します。drive_share_link は URL 自体が秘密となる公開リンクを作成するため、共有するつもりのファイルにのみ使用してください。send_message では、たとえば drive_download で取得したばかりのファイルなど、ローカルファイルを添付することもできます。

送信ポリシー（許可リストと確認）

send_message は、宛先の許可リストと任意の「送信前に確認」ルールによって管理されます。エージェントはどちらも読み取り、変更できます。

• email_policy_status は現在の許可リストと、確認が有効かどうかを表示します。
• email_allow は許可リストを設定します。送信先を制限するには特定のアドレスまたは glob（*@company.com）を指定し、誰にでも送信できるようにするには ["*"] を、すべての送信をブロックするには [] を指定します。
• set_send_confirmation は確認ルールを有効または無効にします。有効な場合、send_message の初回呼び出しでは何も送信せず、確認要求を返します。confirm=true を指定して再度呼び出した場合にのみ送信します。

この3つのツールはエージェントが変更できるため、それだけでは便利な助言にとどまります。強制制御は、環境変数または protonlite policy CLI を使って人が別途設定するもので、エージェントが緩和することはできません。

• 宛先の上限。 PROTON_ALLOWED_RECIPIENTS（カンマ区切りのアドレス／glob）、または protonlite policy ceiling <addrs> は、email_allow ツールが超えられない上限です。エージェントの操作にかかわらず、リスト外の宛先への送信は拒否されます。
• 強制確認。 PROTON_REQUIRE_SEND_CONFIRMATION=1、または protonlite policy require-confirm on を設定すると、エージェントによる send_message は完全に無効になります。常に拒否され、confirm 引数でも解除できないため、人が protonlite send を使ってターミナルから送信します。（エージェント自身の set_send_confirmation が制御するのは、confirm=true で十分な、より緩やかな2段階ルールだけです。意図的なエージェントや操作されたエージェントは自ら confirm=true を渡せるため、これは障壁ではなくチェックポイントです。）

ターミナルから強制ポリシーを管理します。

protonlite policy show                         # print the effective policy
protonlite policy ceiling *@your-company.com   # a ceiling the agent cannot exceed
protonlite policy require-confirm on            # agent can no longer send; you send via the CLI
protonlite policy require-confirm off           # lift it

また、各ツール呼び出しの承認を求める MCP クライアントでのみサーバーを実行してください。send_message と drive_upload はローカルファイルを読み取り、外部に送信できるためです。エージェントが決して回避できない送信ゲートとして、すべての送信に対するフェイルクローズの人による承認フックを使うには、以下の hermes-proton をご覧ください。

ステータスと制限事項

書き込み処理（Drive へのアップロード、カレンダーイベントの作成、共有リンク）は、Proton の Go クライアントとウェブクライアントをリバースエンジニアリングして実装し、実際のアカウントで検証しました。ただし、API は公開ドキュメントがなく、変更される可能性があります。カレンダーキーの生成では gpg を外部呼び出しします（Proton は PGPy では生成できない Ed25519 キーを必要とします）。バグ報告や PR を歓迎します。

関連

protonlite は、Hermes Agent 用の Proton プラグインである hermes-proton のエンジンとしても使われています。このプラグインは、宛先の許可リストと、すべての送信に対する人による承認ゲートを追加します。

ライセンス

MIT です。LICENSE をご覧ください。