simplelogin-mcp

simplelogin-mcp

既存の SimpleLogin ユーザー向けの、独立したセルフホスト可能な Model Context Protocol サーバーです。互換性のある MCP クライアントから、サーバーを自分で実行してエイリアスの作成と管理、エイリアスのアクティビティメタデータの確認、リバースエイリアスの操作、ルーティングの管理、アカウント設定の確認ができます。

独立したプロジェクト： simplelogin-mcp は、独立したオープンソースプロジェクトです。SimpleLogin または Proton AG の公式製品、サービス、MCP 実装ではなく、SimpleLogin または Proton AG と提携、推奨、後援のいずれの関係もありません。

概要

• ローカル stdio は、1 つのローカル MCP クライアントで始める最も簡単な方法です。クライアントがネットワークリスナーを開かずにサーバーを起動します。
• Node.js を直接実行 — Streamable HTTP は、HTTP 対応の MCP クライアント向けの常駐サービスを実行します。デフォルトではループバックで待ち受けます。
• Docker Compose — Streamable HTTP は、Docker でサービスを管理したい場合に公開済みコンテナを実行します。デフォルトではホストからの公開はループバックのみに制限されます。
• SL_API_KEY を使うと SimpleLogin アカウントを完全に操作できます。プロンプト、ログ、シェル履歴、バージョン管理に含めないでください。
• ツール名、入力、安全性に関する注釈、上限、出力の説明には、サーバーで使用されているものと同じカタログとスキーマが使用されます。

ドキュメント

ウェブサイトがユーザー向けドキュメントの正式な情報源です。

• はじめに
• SimpleLogin API キーの作成
• MCP クライアントのセットアップ
• ツールカタログを見る
• API の対応状況と対象外の機能を確認する
• セキュリティとデータについて
• 稼働中のデプロイを運用する
• インストールのトラブルシューティング
• 公開済みコンテナパッケージを見る

リポジトリのメンテナー向けドキュメントは、コードと一緒に管理されています。

• ライブスモークテストの手順書
• レジストリへの登録準備
• リリース手順
• コントリビューションガイド
• サポートポリシー
• 脆弱性の報告

ツール

カタログには、エイリアス、連絡先とリバースエイリアス、メールボックス、カスタムドメイン、通知、アカウント設定に関するツールが含まれます。大量の結果が返る可能性のある読み取り操作には上限が設けられており、完全削除には明示的な確認が必要です。

現在公開されている機能は、検索可能なウェブサイトのツールカタログで確認するか、ソースと一緒に生成される TOOL_CATALOG.md を参照してください。エンドポイント単位の対応状況と意図的に対象外としている機能については、API の対応状況に記載されています。

よくあるワークフロー

ワークフローガイドでは、確認しながら進められる一連の手順を紹介しています。ここでは、よく使われる開始方法を要約しています。

エイリアスの作成と整理

既存のエイリアスを alias_list で確認してから、alias_create_random で新しいエイリアスを作成します。カスタムアドレスを使う場合は、alias_create_custom を呼び出す前に alias_options_get でオプションを確認してください。alias_update でメモ、名前、ピン留め状態を整理し、alias_set_enabled でエイリアスを明示的に有効または無効にします。

私が SimpleLogin のエイリアスをどのように整理しているか、個人的な例については、メールを整理する方法をご覧ください。

最近のエイリアスアクティビティを監査する

alias_list または alias_get でエイリアスを見つけてから、alias_activity_list で範囲を限定したアクティビティメタデータのページを確認します。 結果には転送、返信、ブロック、バウンスが記録されます。サーバーがメール本文を読み取ることはありません。

送信用の逆エイリアスを作成する

contact_list でエイリアスの既存の宛先を確認してから、必要に応じて contact_create で逆エイリアスを作成または再利用します。エイリアスを所有する実際のメールボックスから、返された逆エイリアスアドレス宛てに実際のメッセージを送信します。MCP サーバーは転送用アドレスを作成しますが、メールの作成や送信は行いません。

メールボックスを管理する

メールボックスを作成、更新、削除する前に mailbox_list を使用します。新しいアドレスは SimpleLogin での認証が必要です。また、完全に削除するには confirm: true と、所有するエイリアスを移管するか削除するかの明示的な選択が必要です。

カスタムドメインを管理する

サーバーは、既存のカスタムドメインについて、サポートされている設定を確認および更新できます。ドメインの作成と削除、DNS、MX の検証は、SimpleLogin の公式インターフェースで行う必要があります。

アカウントを確認する

アカウントの集計件数には account_get_stats、範囲を限定したアカウント通知には notification_list を使用します。サポートされている変更を settings_update で行う前に、settings_get で設定を確認してください。

インストールと実行

前提条件

• 専用 API キーを設定した SimpleLogin アカウント。
• Git。
• ソースからインストールする場合：Corepack と pnpm 11.5.1 を備えた Node.js 24.x。
• コンテナーでインストールする場合：Docker と Docker Compose。
• 選択したトランスポート（ローカル stdio または Streamable HTTP）をサポートする MCP クライアント。

ローカル stdio

クライアントとサーバーを同じマシンで実行する場合は、ローカル stdio から始めることをおすすめします。

git clone https://github.com/enthouan/simplelogin-mcp.git
cd simplelogin-mcp
corepack enable
pnpm install --filter simplelogin-mcp --frozen-lockfile
pnpm build

次に、お使いの MCP クライアント向けの手順に従い、dist/index.js の絶対パスを指定します。クライアントの非公開設定に TRANSPORT=stdio と SL_API_KEY を設定し、クライアントを再起動して、ドキュメントに記載された読み取り専用の呼び出しで検出を確認します。

Docker Compose

運用者が管理する永続サービスには、同梱の Compose ファイルを使用します。

git clone https://github.com/enthouan/simplelogin-mcp.git
cd simplelogin-mcp
cp .env.example .env
# Set SL_API_KEY and MCP_AUTH_TOKEN in .env
docker compose up -d
docker compose ps
curl http://localhost:3000/health

v1.0.4 の応答は {"status":"ok","version":"1.0.4"} です。

デフォルトのファイルは公開済み GHCR イメージを取得し、ホストポートを 127.0.0.1 でのみ公開します。また、アプリケーションがコンテナー内で 0.0.0.0 にバインドするため、MCP_AUTH_TOKEN が必要です。デプロイを再現可能にするには、SIMPLELOGIN_MCP_IMAGE_TAG にリリースを指定してください。ホストのバインド範囲を広げる前に、Docker Compose ガイドを参照してください。

ローカル Docker ビルド

ソースを変更する場合は、GHCR から取得する代わりに、チェックアウトしたソースからコンテナーをビルドします。

docker compose -f docker-compose.local.yml up --build

直接 Node.js — Streamable HTTP

直接 Node.js で Streamable HTTP の開発を行うには、.env.example をコピーし、SL_API_KEY を設定して、無視対象のファイルをサブシェル内でのみ読み込みます。

corepack enable
pnpm install --filter simplelogin-mcp --frozen-lockfile
cp .env.example .env
pnpm build
(
  set -a
  . ./.env
  set +a
  TRANSPORT=http HOST=127.0.0.1 PORT=3000 pnpm start
)

MCP エンドポイントは POST http://127.0.0.1:3000/mcp です。GET /health で確認できるのはプロセスの状態のみです。クライアント認証と広域ネットワークでの要件については、Streamable HTTP ガイドを参照してください。

設定

設定は環境変数で指定し、起動時に検証されます。主な設定項目は次のとおりです。

変数	用途
SL_API_KEY	必須の SimpleLogin 認証情報です。アカウントを完全に管理できます。
TRANSPORT	stdio または http を指定します。デフォルトは http です。
SL_API_URL	ホスト型またはセルフホスト型 SimpleLogin Web アプリのオリジンです。
HOST / PORT	Streamable HTTP リスナーを直接指定します。デフォルトは 127.0.0.1:3000 です。
MCP_AUTH_TOKEN	POST /mcp を保護する個別のベアラートークンです。通常のループバック以外での起動には必須です。

Compose のポート公開、許可するブラウザーオリジン、タイムアウト、プライベート CA、プロキシ変数については、完全な設定リファレンスを参照してください。

SimpleLogin API キーの取得

SimpleLogin ダッシュボードで専用のキーを作成し、非公開にしてください。ホスト型およびセルフホスト型のインスタンスについては、API キーガイドに従ってください。

クライアントの接続

Codex、Claude Code、Claude Desktop、VS Code、OpenCode については、メンテナンスされているクライアント設定レシピを利用してください。互換性ページでは、現在の検証結果の範囲と制限事項を説明しています。

クライアントがサーバーを検出したら、「SimpleLogin アカウントの使用状況を表示してもらえますか？」と尋ねてください。想定されるツールは account_get_stats です。これは引数を取らない読み取り専用の呼び出しで、アカウントの集計数を返します。この呼び出しが成功すれば、クライアントの接続と SimpleLogin へのアクセスを確認できます。GET /health で確認できるのは、HTTP サーバーが稼働していることだけです。

セルフホスト型 SimpleLogin

SL_API_URL には /api サフィックスを付けずにセルフホスト型 Web アプリのオリジンを設定し、同じインスタンスで SL_API_KEY を作成してください。プライベート CA とプロキシの設定については、設定リファレンスに記載されています。互換性は、インスタンスが上流と互換性のある API パスとレスポンス形式を提供しているかどうかに依存します。

トラブルシューティング

まずトラブルシューティングガイドを参照してください。API キー、ベアラートークン、認証ヘッダー、プロキシ認証情報、エイリアスアドレス、メールボックスアドレスをログや課題に含めないでください。サポートの範囲については、SUPPORT.mdを参照してください。

開発

Node.js 24.x と pnpm が必要です。

pnpm install --frozen-lockfile
pnpm build
pnpm typecheck
pnpm lint
pnpm test
pnpm format:check

ウォッチサーバーを起動するには、設定を環境に読み込んだ後、pnpm dev を実行してください。ローカルの pnpm コマンドは .env を自動的に読み込みません。サブシェルで読み込む方法については、Node.js を直接使う例を参照してください。

エンドポイントのパターン、カタログの生成、テスト、プルリクエストの要件については、CONTRIBUTING.mdを参照してください。SimpleLogin を使ったライブスモークテストは一時的なエイリアスを作成するため、手動でのオプトイン方式です。docs/live-smoke-test.mdを参照し、クリーンアップが行われたことを確認してください。

アーキテクチャ

エンドポイントのサポートは、定数、レスポンススキーマ、SimpleLogin クライアント、ツールカタログ、登録処理に分かれています。共有リクエストレイヤーは、認証、タイムアウト、エラーの正規化、レスポンスの検証を処理します。変更の具体的なパターンについてはCONTRIBUTING.mdを、実行時のリクエストフローについては仕組みを参照してください。

セキュリティ

SL_API_KEY はパスワードと同様に扱ってください。ローカルの stdio ではリスナーを開きません。Streamable HTTP はデフォルトでループバックにバインドされ、通常の未認証の非ループバック起動を拒否します。LAN またはパブリック環境にデプロイする場合は、MCP_AUTH_TOKEN を有効にしたままにし、リバースプロキシで TLS を終端してください。

脆弱性を報告する前に SECURITY.md をお読みください。質問やセキュリティ以外のバグについては SUPPORT.md をご利用ください。

コントリビューション

コントリビューションを歓迎します。プルリクエストを作成する前に CONTRIBUTING.md をお読みください。

ライセンス

MIT — LICENSE をご覧ください。