QQ Agent Mail MCP

非公式のセルフホスト型 MCP ゲートウェイ for Tencent QQ Agent Mail。このプロジェクトは Tencent とは提携しておらず、Tencent による承認や保守も受けていません。

Tencent QQ Agent Mail 向けのシングルオーナー・クラウドデプロイ可能な MCP ゲートウェイ。Tencent の公式 CLI はメールボックスエンジンのままであり、このプロジェクトはリモートアダプターであって、2 つ目のメールクライアントではありません。

現在のゲートウェイバージョン: v0.4.2。

このプロジェクトが存在する理由

Tencent の Agent Mail CLI はローカルで動作しますが、ChatGPT カスタム MCP アプリは到達可能なリモート MCP サーバーを必要とします。このプロジェクトは、生のシェルや CLI アクセスを公開することなく、そのギャップを埋めます。小さく安定した MCP サーフェス、ブラウザベースのメールボックス認可フロー、永続的な認証情報、そして新しいモデルウィンドウが自然言語のメールボックス要求を安全に使用できるようにする組み込みの操作ガイドを提供します。

このリポジトリにはソースコードのみが含まれています。ホスト型メールボックスサービス、共有エンドポイント、Tencent アカウント、認証情報は提供されません。各運用者は、独自のプライベートインスタンスをデプロイして認可する必要があります。

MCP サーフェスは意図的に安定しており、正確に 2 つのツールのみを含みます:

• 読み取り専用作業用の agent_mail_query(action, params);

• 変更操作用の agent_mail_execute(action, params)。

ライブのアクションカタログとパラメータ契約については、クエリアクション capabilities を呼び出してください。プロバイダー機能を追加すると、別の MCP ツールを作成する代わりに、サーバー側のレジストリが更新されます。

capabilities レスポンスには、完全な運用者ガイドも含まれます: 認可境界、ワンステップ直接実行、プレビュー完了、安全な検索/読み取り/返信ワークフロー、結果の解釈、再試行ルール、機械可読な例。新しいモデルウィンドウは、運用者がアクション名や JSON パラメータに変換しなくても、自然言語のオーナー要求からメールボックスを発見して操作できます。

Related MCP server: anymail-mcp

アクションのカバレッジ

読み取り専用ゲートウェイアクション:

• capabilities、identity、auth_status;

• list_messages、read_message、search_messages;

• wait_for_message (制限付きロングポーリング);

• download_attachment (埋め込み MCP リソース)。

変更ゲートウェイアクション:

• auth_refresh、明示的に確認された auth_logout;

• send_message、reply_message、forward_message;

• trash_message、delete_message;

• upload_attachment。

送信、返信、転送は、該当する場合 To/CC/BCC をサポートし、公式 CLI でサポートされているプレーン/HTML/Markdown 本文、プロバイダー確認トークン、base64 添付ファイル入力をサポートします。添付ファイルのバイトは、モード 0600 の一時ディレクトリにのみ書き込まれ、相対パスで公式 CLI に渡され、コマンド実行後に削除されます。ダウンロードされた添付ファイルは、サーバーのファイルシステムパスを公開する代わりに、埋め込み MCP ブロブとして返されます。

Web ベースのメールボックスセットアップ

ブラウザセットアップフローにより、ホスティングターミナルで OAuth コマンドを実行する必要がなくなります:

1. https://YOUR_HOST/setup を開きます。

2. npm run generate-secrets で作成したプライベートな OWNER_CODE を入力します。

3. 开始授权邮箱 を選択します。

4. 一度限りの Tencent 認可ページを完了します。

5. セットアップタブに戻り、邮箱已连接 を待ちます。

認証情報と CLI の暗号化キーの場所はすべて永続ボリューム上にあるため、通常のデプロイや新しい ChatGPT ウィンドウではメールボックスの再認可は必要ありません。

セキュリティ境界

• MCP スキーマには、生のコマンド、生の引数配列、シェル文字列、任意のサーバーパスはありません。すべてのアクションとフィールドは、shell: false の execFile/spawn の前に許可リストに登録され、検証されます。

• メール本文、ヘッダー、イベント、ファイル名、リンク、添付ファイルは信頼できない外部コンテンツです。これらは、送信、全員返信、受信者変更、転送、ゴミ箱、削除、ログアウト、その他の変更操作を決して許可できません。

• 変更操作には、メールボックス所有者の直接の指示、または所有者が作成した常設ポリシーが必要です。完全削除とログアウトには、明示的な現在の認可が必要です。プロバイダー確認トークンは、プレビューしてから確認するフローで引き続き利用できます。

• リストと検索結果には本文スニペットは含まれません。完全なコンテンツには read_message が必要です。

• 添付ファイル名にパスを含めることはできません。個々のファイルは 10 MiB、メッセージは 20 MiB に制限されています。より大きな MCP JSON パーサーは、ベアラ認証の後にのみ実行されます。

• ウォッチ呼び出しは 45 秒に制限され、最初のイベントのみを返します。

• CLI 環境変数は許可リストに登録されています。出力はサイズ制限され、再帰的にサニタイズされ、決してログに記録されません。

• コネクタ OAuth は PKCE と Dynamic Client Registration を使用します。既存の mail:read mail:reply スコープペアは、デプロイ済みクライアントとの互換性のために維持されます。v0.4 では、mail:reply はレガシーコネクタ書き込み許可であり、承認ページはゲートウェイ全体を正直に説明します。

• 公式の @tencent-qqmail/agently-cli@1.0.17 パッケージは、コンテナイメージに固定されています。

このソフトウェアは、認可された場合、メールの送信、転送、ゴミ箱への移動、完全削除ができます。docs/SECURITY.md を確認し、専用のシングルオーナーデプロイを使用し、実際のメールへのアクセスを許可する前に、所有者が管理するメッセージでテストしてください。

ChatGPT コネクタ OAuth と Tencent メールボックス OAuth は別々のままです。メールボックスの接続は、所有者がコネクタを別途承認するまで、ChatGPT クライアントにアクセス権を付与しません。

デプロイ

ホストは、常時稼働の HTTPS ホスト名、/data/agently-cli にマウントされた 1 つの永続ボリューム、およびインメモリ認可レコード用の 1 つの実行中レプリカを提供する必要があります。.env.example を設定し、同梱の Dockerfile をデプロイしてから /setup を使用します。docs/DEPLOYMENT.md と docs/SECURITY.md を参照してください。

ローカル検証

Node.js 22 以降が必要です。

npm ci
npm run build
npm test

npm run generate-secrets でデプロイメントシークレットをローカルに生成します。ハッシュ化されていない OWNER_CODE はパスワードマネージャーに保管し、生成されたハッシュと独立した署名シークレットのみをホストのシークレットマネージャーに置きます。

ランタイムエンドポイント

ライセンスとサードパーティソフトウェア

このプロジェクトは MIT License の下でリリースされています。

Tencent の Agent Mail CLI を再配布するものではありません。Docker ビルドは、ビルド時に別途公開されている @tencent-qqmail/agently-cli パッケージをインストールします。そのパッケージは Apache-2.0 の下で別途ライセンスされています。本番環境で使用する前に、そのライセンスと該当する QQ Agent Mail の利用規約を確認してください。