MCPでAIエージェントをTrekMailに接続

TrekMail MCPサーバーを使うと、互換性のあるAIクライアントから自然言語でメールインフラを管理できます。同じTrekMail APIを通じて、ドメイン、メールボックス、White Labelのブランド設定とチーム、Drive、メール、カレンダー、移行、サポート、請求、関連サービスを扱うカタログを提供します。

すべての会話に完全なカタログが読み込まれるわけではありません。TrekMailは有効な認証情報からtools/listを構築します。認証範囲外のツールに加え、選択したツールセット、読み取り専用モード、トランスポート制限、ローカルの安全設定で除外されたツールも省かれます。そのため、メール用に範囲を限定した認証情報では、コンパクトなメールツール一覧が提示されます。

接続方法を選ぶ

方法1-3ではOAuth 2.1を使用します。初回接続時にブラウザでTrekMailの同意ページが開き、要求された権限を確認すると、クライアントはアカウントに限定されたトークンを取得します。長期間有効なtm_live_トークンをクライアントへコピーする必要はありません。接続はいつでもAIエージェントとAPI → トークン → 接続済みアプリから取り消せます。

利用できる機能

• 接続ごとのツールセットは、登録前に現在の接続の権限と安全設定に基づいて絞り込まれます。
• OAuth 2.1 + 動的クライアント登録: AIクライアントが自身を登録し、ブラウザの同意ページを案内して、範囲付きトークンを取得します。Web、デスクトップ、CLIの各方法で長期間有効なトークンをコピーして貼り付ける必要はありません。
• デュアルトークン構成: インフラ用のオペレーショントークンと、Webメールの全操作用のメッセージトークンを分けます。OAuthで接続すると、必要に応じてメールボックスごとにメッセージトークンが自動発行されます。
• 自動的な冪等性が必要な操作に適用されるため、再試行しても同じ操作が重複しません。
• 二段階の削除: メールボックスの削除には明示的な意思表示と確認が必要で、その後、復元できるよう「最近削除した項目」に移動します。
• セルフホスト用の安全制御: 独自のstdio MCPサーバーを運用する管理者は、削除、送信、移行操作に承認を必須にできます。
• 完全な監査ログ: すべてのAPIおよびMCP操作が記録され、90日間保持されます。

始める前に

• すべてのプランでエージェントを接続できます。
  • Nano: メール検証ツール。Drive Storageを追加すると、閲覧、アップロード、共有、復元、完全削除など、アカウントに付与されたDrive機能もエージェントが利用できます。
  • Starter: Driveとメール検証の全機能に加え、その他の領域（ドメイン、メールボックス、移行、チケットなど）への読み取り専用アクセス。移行の作成、チケットへの返信、自動返信の変更など、StarterがAPI経由で提供しない書き込み操作にはダッシュボードを使用します。
  • Pro / Agency: すべての機能群に対する完全な読み取りおよび書き込みアクセス。
  • White Labelのトライアルまたはアドオン: 権利が有効な間、ブランド、クライアント/チーム、アクティビティのツールを追加します。権利がなければ、それらのスキーマは省かれます。解約猶予期間中は、所有者だけが読み取りツールを利用できます。
• 初めてですか？ AIエージェントとAPIページのツアーを開始ボタンでは、エージェントの接続、クライアントごとの手順、手動トークン、接続済みアプリ、監査ログを順に確認できます。
• **OAuthを使う方法（1、2、3）**では、トークンを手動作成する必要はありません。クライアントがブラウザ認証フローで作成します。**セルフホストstdioの方法（4）**では、最初にダッシュボードでtm_live_トークンを作成してください。

1. リモートMCPクライアント（推奨）

AIクライアントがリモートMCPサーバーとブラウザ認証に対応している場合は、この方法を使用します。

ショートカット: AIエージェントとAPIページのエージェントを接続タブで使用中のクライアントを選ぶと、 そのクライアントに固有の経路、メニューパス、または設定ファイルと、アドレスを入力済みのスニペットが 表示されます。クライアントが一覧にある場合は、以下の一般的な手順ではなく、表示された手順に 従ってください。

1. クライアントでMCP、連携、またはコネクタの設定を開きます。
2. リモートMCPサーバーを追加またはカスタムコネクタを追加を選びます。正確な名称はクライアントによって異なります。
3. 次を入力します。
   • 名前: TrekMail
   • リモートMCPサーバーURL: https://trekmail.net/mcp
4. 接続を確定します。ブラウザでTrekMailの認証ページが開きます。
5. サインインして要求された権限を確認し、アクセスを承認します。ブラウザで接続が確認されたらクライアントに戻ります。

最初の認証で有効期限付きトークンが発行されます。対応クライアントは自動的に更新します。接続を解除するには、クライアントの切断操作を使用するか、TrekMailのトークン → 接続済みアプリからアプリを取り消します。

2. CLIまたはデスクトップクライアント

stdioコマンドを受け付けるクライアントでは、次のクライアント共通ブリッジを使用します。

npx -y mcp-remote https://trekmail.net/mcp

このコマンドをクライアントのMCPサーバーとして設定します。初回接続時にブラウザが開き、認証を行います。

独自のリモートMCPサーバー追加コマンドを提供するクライアントもあります。その方法でも問題ありません。サーバーURLにhttps://trekmail.net/mcpを指定し、クライアントの案内に従ってください。

クライアント別の例: Claude Code

claude mcp add trekmail https://trekmail.net/mcp -t http

クライアント別の例: Claude Desktop

設定ファイル（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json）を編集し、次を追加します。

{
  "mcpServers": {
    "trekmail": {
      "url": "https://trekmail.net/mcp",
      "transport": "http"
    }
  }
}

Claude Desktopを再起動します。チャットで初めてTrekMailに言及すると、OAuthポップアップが開きます。

クライアント別の例: Cursor

Cursorにはリモートサーバー用の画面がありません。~/.cursor/mcp.json（またはプロジェクト内の.cursor/mcp.json）を 読み込みます。

{
  "mcpServers": {
    "trekmail": {
      "url": "https://trekmail.net/mcp"
    }
  }
}

クライアント別の例: Windsurf

Windsurfは~/.codeium/windsurf/mcp_config.jsonを読み込みます。キーはserverUrlであり、urlではありません。 urlで設定したリモートサーバーは無視されます。

{
  "mcpServers": {
    "trekmail": {
      "serverUrl": "https://trekmail.net/mcp"
    }
  }
}

ファイルを保存し、変更が読み込まれるようクライアントを再起動します。初回接続時にはアクセス承認のため ブラウザが開きます。

3. mcp-remote（CLI）

テストや、リモートOAuthサーバーにまだ直接対応していないAnthropic以外のMCPクライアントには、stdioからリモートHTTPへの小さなNodeブリッジであるmcp-remoteが便利です。

npx -y mcp-remote https://trekmail.net/mcp

初回実行時にOAuth用のブラウザが開きます。その後、トークンは~/.mcp-auth/にキャッシュされ、自動的に使用されます。

ローカルのNodeエントリポイントではなくmcp-remoteコマンドを指定すれば、任意のstdio MCPクライアントに組み込めます。

4. セルフホストstdio（Claude Desktop / Docker / npm）

OAuthの代わりに静的なtm_live_トークンを使用したい場合、たとえば無人サーバー、非公開TrekMailインスタンス、コンテナ配備では、stdio MCPパッケージをクローンして自分のホストで実行します。

まずAIエージェントとAPI → トークンページでAPIトークンを作成します。メールを読み書きする場合は、オペレーショントークンを使ってAPI経由でメッセージトークンも作成します。手順はエージェントを接続タブを参照してください。

MCPサーバーをインストールする

git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
npm install
npm run build

Claude Desktop（stdio）

Claude DesktopのMCP設定ファイルに次を追加します。

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "trekmail": {
      "command": "node",
      "args": ["./trekmail-mcp/build/index.js"],
      "env": {
        "TREKMAIL_BASE_URL": "https://trekmail.net",
        "TREKMAIL_API_TOKEN": "tm_live_your_token",
        "TREKMAIL_MESSAGE_TOKEN": "tm_msg_your_token",
        "TREKMAIL_ALLOW_SENDING": "false",
        "TREKMAIL_ALLOW_MIGRATION": "false"
      }
    }
  }
}

クローンしたリポジトリの場所を指すようargsのパスを更新し、トークンを自分のものに置き換えます。インフラツールだけが必要ならTREKMAIL_MESSAGE_TOKENを、メッセージツールだけが必要ならTREKMAIL_API_TOKENを省略できます。少なくとも一つのトークンが必要です。

Claude Code（stdio）

Claude CodeのMCP設定（.claude/settings.jsonまたはプロジェクト単位の設定）に次を追加します。

{
  "mcpServers": {
    "trekmail": {
      "command": "node",
      "args": ["./trekmail-mcp/build/index.js"],
      "env": {
        "TREKMAIL_BASE_URL": "https://trekmail.net",
        "TREKMAIL_API_TOKEN": "tm_live_your_token",
        "TREKMAIL_MESSAGE_TOKEN": "tm_msg_your_token",
        "TREKMAIL_ALLOW_SENDING": "false",
        "TREKMAIL_ALLOW_MIGRATION": "false"
      }
    }
  }
}

Docker

Dockerを使用する場合は、リポジトリからイメージをビルドして実行します。

git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
docker build -t trekmail-mcp .

docker run -i \
  -e TREKMAIL_BASE_URL=https://trekmail.net \
  -e TREKMAIL_API_TOKEN=tm_live_your_token \
  -e TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token \
  -e TREKMAIL_ALLOW_SENDING=false \
  -e TREKMAIL_ALLOW_MIGRATION=false \
  trekmail-mcp

ローカルnpm（開発）

git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
npm install && npm run build

TREKMAIL_BASE_URL=https://trekmail.net \
TREKMAIL_API_TOKEN=tm_live_your_token \
TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token \
TREKMAIL_ALLOW_SENDING=false \
TREKMAIL_ALLOW_MIGRATION=false \
npm start

stdio環境変数

これらの制御は、自分で実行するセルフホストstdio MCPプロセスだけに適用されます。TrekMail製品の機能をオンまたはオフにするものではありません。

エージェント向けDriveツール

Driveのスコープを含むオペレーショントークンを使うと、MCPサーバーはスペース、使用量、閲覧、アップロード、ファイル、フォルダ、ゴミ箱、一括操作、公開共有リンク、同期デバイス用パスワード管理、Drive Add-onの状態に関するツールを提供します。接続には、そのスコープで許可されたツールが表示されます。

Drive専用エージェントではTREKMAIL_API_TOKENを設定し、ワークフローに必要なスコープだけを付与します。stdioをセルフホストする場合、エージェントが確認済みの完全削除またはゴミ箱を空にするジョブを実行するとき以外は、破壊的操作を無効にしてください。Drive Add-onの購入、容量変更、解約はMCPツールではありません。エージェントはアドオンの状態と料金を確認できますが、請求の変更はダッシュボードで行います。

Drive MCPツールの概要とAIエージェントをTrekMail Driveに接続も参照してください。

利用可能なツール

MCPサーバーは接続済みエージェントに次のツールを提供します。提供されたトークンに応じて、ツールは条件付きで登録されます。

エージェントが実際に表示できるツールは三つの要素で決まり、いずれもtools/listが応答する前に適用されます。

1. トークンのスコープ。 トークンが機能のスコープを持たないツールは登録されません。
2. ローカルstdioの安全制御。 セルフホストstdioサーバーでは、管理者が書き込み、送信、移行操作に承認を要求できます。ホスト型MCPでは、代わりにOAuthで承認されたスコープを使用します。
3. **TREKMAIL_READ_ONLY=true**は、スコープやフラグに関係なく、すべての書き込みツールを除外します。

そのため、トークンのスコープが広くても、セルフホスト接続を意図的に制限できます。ホスト型MCPはOAuthで承認された権限に引き続き限定されます。

ドメインツール（オペレーショントークン）

プランごとの動作、応答状態、安全な解除、受信専用ルーティング規則については、APIとMCPによるドメインエイリアスを参照してください。

White Labelツール（オペレーショントークン）

white_labelツールセットには20個のツールが含まれ、アカウントの権利、現在のメンバーシップ、認証情報のスコープで許可される場合だけ表示されます。ブランド設定はドメインごとに行い、残りのツールはセットアップ、クライアント、チームアクセス、アクティビティを管理します。書き込みには有効なWhite Labelが必要です。解約猶予期間中は所有者だけが読み取りツールを保持します。

エージェントはブランド設定を最初から最後まで実行できます。ブランドを設定し、返されたdns_recordsをコピーしてapply_cloudflare_dnsで公開し、検証して状態を確認します。アクセスを変更する呼び出しは、トークンがより広いスコープを要求していても、呼び出し元の有効なメンバーシップとドメイン境界によって制限されます。White Labelブランド設定のAPIおよびMCPガイドとAPIおよびMCPでWhite Labelチームを管理も参照してください。

DNSツール（オペレーショントークン）

メールボックスツール（オペレーショントークン）

共有メールボックスツール（オペレーショントークン）

共有メールボックスは、メンバーが自分の通常メールボックスアカウントからWebメールで開くチーム受信箱（support@、sales@）です。有効な場合は委任されたネイティブIMAP/SMTPアクセスも使用できます。直接のパスワードログインはありません。アクセスは一律で全員が読み取れ、can_sendだけを切り替えられます（返信可能または読み取り専用）。メンバーの役割はありません。

共有メールボックスのライフサイクル（オペレーショントークン）

三つのライフサイクルツールと三つのメンバー書き込みツールはアクセスを変更します。ローカルホストのstdio管理者は、これらの提供前にTREKMAIL_ALLOW_DESTRUCTIVE=trueを必須にできます。list_shared_mailbox_membersは読み取り専用で、常に利用できます。

作成、変換、メンバー変更の後、通常メンバーのメールボックスIDを指定してget_mail_client_setupを呼び出します。shared_mailboxes.items[]を確認し、native_access_ready=trueになるまで待ち、送信を設定する前にsend_as_readyを確認してください。応答には受信箱/送信済み/アーカイブ/迷惑メールの正確なパスと操作フラグが含まれます。SMTPは共有の送信済みコピーを保存しません。権限の削除、権限の更新、変換で再試行可能なnative_access_sync_failedが返された場合、サービスが意図的に以前の状態を維持したことを示します。

Sieveツール（オペレーショントークン）

削除ツール（オペレーショントークン）

移行ツール（オペレーショントークン）

チケットツール（オペレーショントークン）

SMTP/ドメインルーティングツール（オペレーショントークン）

SMTPはドメインごとに設定します。各ドメインは、管理型プラットフォーム送信または保存済みSMTPプロファイル（独自プロバイダーで、複数ドメインに再利用可能）を指定し、アカウント全体で一つのデフォルトが新規ドメインの初期設定を決めます。

上記の書き込みおよびテストツールは設定を変更するか接続テストを実行します。ローカルホストのstdio管理者は、これらの提供前にTREKMAIL_ALLOW_DESTRUCTIVE=trueを必須にできます。get_domain_smtp、list_domain_smtp_profiles、get_domain_smtp_test_status、get_account_smtp_defaultは読み取り専用で常に利用できます。

従来のSMTPツール（非推奨）

次のアカウント単位のツールは後方互換性のために残されていますが、ドメインごとのルーティングは制御しません。代わりに上記のドメインルーティングツールを使用してください。

スパム指標ツール（オペレーショントークン）

アカウントツール（オペレーショントークン）

メッセージトークン管理（オペレーショントークン）

メッセージツール（メッセージトークン）

メッセージトークンは、接続済み外部アカウントを含むWebメールの全機能を扱う62個のツールを有効にします。ツールは機能領域ごとに整理されています。

ホスト型OAuthとローカルstdioでは、メールボックスの識別方法が異なります。ホスト型HTTP MCPでは、すべてのメッセージツールのスキーマに必須のmailbox_idがあり、サーバーはそれを使って対象メールボックス用の短期トークンを発行します。ローカルstdio MCPでは、TREKMAIL_MESSAGE_TOKENがすでに一つのメールボックスに紐付いているため、同じツールはmailbox_idを受け付けません。接続済み受信箱は二つ目の選択階層です。ホスト型MCPではexternal_account_idをmailbox_idに加えて、stdioでは紐付いたメッセージトークンに加えて指定します。

62個のメッセージツールのうち七つは接続済みアカウントを、五つはFrom IDと返信ポリシーを管理します。エージェントが接続済みGmail受信箱を読みながら、ドメインルートまたは保存済みSMTPプロファイルを通じて認証済みビジネスアドレスから送信するGmail形式のワークフローでは、両方の機能群を使用します。APIとMCPによるSend Asアドレスも参照してください。

基本メッセージ

メールボックスの設定 → プロフィールでデフォルトCCまたはデフォルトBCCが設定されている場合、Webアプリで作成したメールと同様に、send_messageとschedule_messageの送信内容へ追加されます。すでにメッセージに含まれるアドレスは重複して追加されません。一つのメッセージだけで無効にするにはapply_default_recipients: falseを渡します。SMTP経由でデスクトップまたはスマートフォンのメールクライアントから送信したメールはAPIを通らないため、この設定の対象外です。 | report_spam | メッセージをスパムとして報告し、迷惑メールへ移動してフィルターを学習 | | report_ham | 迷惑メール内のメッセージをスパムではないと指定し、受信箱へ移動してフィルターを学習 | | bulk_action | 最大50件のメッセージに操作（既読、スター、削除、移動、スパム）を一括適用 |

フォルダ

添付ファイル

下書き

どちらも下書きのuidとuidvalidityを返します。この組を一緒に保持してください。update_draftにはエポックが必要なので、下書きフォルダの再作成後に、古く再利用されたUIDが別のメッセージを削除することはありません。list_messagesで見つけた下書きは、まずread_messageで開いて現在のuidvalidityを取得します。更新時には新しい組が返され、古いUIDは機能しなくなります。UIDPLUSのないサーバーでは、新しい下書きが保存されても両方の値がnullになる場合があります。更新前に下書きフォルダを再読み込みして下書きを開いてください。

どちらもオプションのidempotency_keyを受け付けます。省略すると各呼び出しが新規として扱われるため、同じ下書きを二度保存すると二つの下書きができます。すでに完了した可能性のある呼び出しを再試行するときは同じキーを渡すと、重複ではなく最初の結果が返ります。

予約送信

連絡先

連絡先グループ

カレンダー

作成補助

これらのツールは返信または転送用のデータを準備します。送信は行いません。返されたデータをsend_messageまたはsave_draftへ直接渡してください。

ID（送信元アドレス）

テンプレート

ブロック済み送信者

メール検証ツール（オペレーショントークン）

メール検証ツールはNanoを含むすべてのプランで利用できます。唯一の制限はクレジット残高です。

Cloudflareツール（オペレーショントークン）

CloudflareツールはProおよびAgencyプランで利用できます。

セルフホストstdioの安全制御

stdio MCPサーバーを自分で実行する場合、TREKMAIL_ALLOW_DESTRUCTIVEはローカルプロセスが削除やその他の書き込み操作を許可するかどうかを制御します。エージェントにメールボックスの削除を任せられる場合だけtrueに設定してください。この設定は、ホスト型TrekMailでの機能の提供状況を変更しません。

破壊的操作を有効にしても、削除には必ず二つの手順が必要で、エージェントはconfirm: trueを明示的に設定する必要があります。詳しくは安全機構と削除意思を参照してください。

送信の安全ゲート

send_messageとschedule_messageには二つの独立した安全ゲートがあり、両方を通過する必要があります。

1. 環境ゲート: MCPサーバーの起動時にTREKMAIL_ALLOW_SENDING=trueを設定する必要があります。
2. 呼び出しごとのゲート: エージェントは毎回の呼び出しでconfirm_send=trueをパラメーターとして渡す必要があります。

この二重ゲート設計により、セルフホストプロセスからの誤送信を防ぎます。エージェントがメッセージを読むだけの場合はTREKMAIL_ALLOW_SENDING=falseに設定してください。list_scheduledはこの制御なしで動作します。この制御は予約メッセージの作成または送信だけに適用されます。

移行の安全ゲート

移行書き込みツール（start_migration、retry_migration、delete_migration、delete_bulk_migration、update_bulk_migration_job_password、test_migration_connection、preview_bulk_migration、start_bulk_migration、retry_bulk_migration）には二つの独立した安全ゲートがあります。

1. 環境ゲート: MCPサーバーの起動時にTREKMAIL_ALLOW_MIGRATION=trueを設定する必要があります。
2. 呼び出しごとのゲート: 各ツールには固有の確認パラメーター（confirm_start=true、confirm_retry=true、confirm_delete=true）が必要です。

cancel_migration、cancel_bulk_migration、resume_bulk_migrationは安全操作または再開操作であるため、セルフホスト環境の制御に関係なく常に利用できます。ただし、呼び出しごとの確認パラメーターは引き続き必要です。

読み取り専用の移行ツール（list_migrations、get_migration、list_bulk_migrations、get_bulk_migration）はゲートなしで動作します。

簡単な解決方法

• エージェントが接続できない: build/index.jsのパスが正しいことと、クローン後にnpm run buildを実行したことを確認してください。
• 「Missing bearer token」エラー: TREKMAIL_API_TOKENまたはTREKMAIL_MESSAGE_TOKENの少なくとも一方が設定されていることを確認してください。
• 読み取り専用ツールは動作するが書き込みに失敗する: トークンがStarterプランです。StarterではDriveの全機能で書き込みが動作します。それ以外の書き込み、メールボックスのプロビジョニング、移行の開始、チケットへの返信には、Proへアップグレードするかダッシュボードを使用してください。
• セルフホストstdioで削除ツールがエラーを返す: そのMCPプロセスの環境でTREKMAIL_ALLOW_DESTRUCTIVE=trueを設定してください。これはメッセージ、フォルダ、連絡先、カレンダー、ID、テンプレート、ブロック済み送信者、予約メッセージなどの削除および書き込み操作に適用されます。
• セルフホストstdioの送信ツールが「Sending is disabled」を返す: そのMCPプロセスの環境でTREKMAIL_ALLOW_SENDING=trueを設定してください。
• 送信ツールが「Send not confirmed」を返す: エージェントはconfirm_send=trueをsend_messageまたはschedule_messageの各呼び出しで渡す必要があります。
• メッセージツールが表示されない: TREKMAIL_MESSAGE_TOKENに有効なtm_msg_トークンが設定されていることを確認してください。
• セルフホストstdioの移行書き込みツールがエラーを返す: そのMCPプロセスの環境でTREKMAIL_ALLOW_MIGRATION=trueを設定してください。
• 移行開始時の503: サーバーが移行処理の上限に達しています。数分後に再試行してください。
• 添付ファイルをダウンロードできない: 添付はBase64で返されます。最大25 MBの大きな添付には数秒かかる場合があります。download_all_attachmentsは全添付をBase64エンコードしたZIPとして返します。
• 更新後に下書きが消えた: update_draftは古い下書きを削除して置換を追加するため、下書きには新しいUID IDが割り当てられます。以降の操作には応答のuidとuidvalidityを両方使用してください。渡した組は置換後の下書きを識別しません。
• 指定していない場所に全メッセージのコピーが届く: メールボックスの設定 → プロフィールでデフォルトCCまたはデフォルトBCCが指定されています。API経由を含め、このメールボックスからの送信に適用されます。そこで解除するか、apply_default_recipients: falseを渡して一つのメッセージだけ無効にしてください。
• カレンダー予定が見つからない: 予定は特定のメールボックスに限定されます。メッセージトークンが正しいメールボックス用に発行されたことを確認してください。