Mailtrap MCP Server

公式

Mailtrap Email APIと統合します。

GitHub
60

ドキュメント

TypeScript test NPM

MCP Mailtrap サーバー

Mailtrap を介したサンドボックスでの送信とテストのためのツールを提供する MCP サーバーです。

前提条件

この MCP サーバーを使用する前に、以下が必要です：

  1. Mailtrap アカウントを作成する
  2. ドメインを検証する
  3. Mailtrap API 設定 から API トークンを取得する
  4. Mailtrap アカウント管理 からアカウント ID を取得する

必要な環境変数:

  • MAILTRAP_API_TOKEN - すべての機能に必須
  • MAILTRAP_ACCOUNT_ID - テンプレート、統計、メールログ、サンドボックス一覧/表示、送信ドメインに必須。send-email と send-sandbox-email ではオプション。

オプション (代わりにツールパラメータとして渡すことも可能):

  • DEFAULT_FROM_EMAIL - send-email または send-sandbox-email に from が指定されていない場合のデフォルト送信者メールアドレス。from パラメータを使用して呼び出しごとに送信者を切り替え可能にします。
  • MAILTRAP_TEST_INBOX_ID - test_inbox_id が指定されていない場合のサンドボックスツールのデフォルトテスト受信箱 ID。test_inbox_id パラメータを使用して呼び出しごとに受信箱を切り替え可能にします。
  • MAILTRAP_SANDBOX_ID - sandbox_id が指定されていない場合のサンドボックスツールのデフォルトサンドボックス ID。sandbox_id パラメータを使用して呼び出しごとにサンドボックスを切り替え可能にします。
  • MAILTRAP_ORGANIZATION_ID - 組織ツール (list-sub-accounts, create-sub-account) に必須。
  • MAILTRAP_ORGANIZATION_API_TOKEN - 組織スコープの API トークン。組織ツールに必須 (MAILTRAP_API_TOKEN とは別)。

クイックインストール

Install in Cursor

Install with Node in VS Code

Smithery CLI

Smithery は、すべての AI クライアントで動作する MCP サーバーのレジストリインストーラー兼マネージャーです。

npx @smithery/cli install mailtrap

Smithery はクライアント設定を自動的に処理し、インタラクティブなセットアッププロセスを提供します。ローカルで MCP サーバーを使い始める最も簡単な方法です。

セットアップ

Claude Desktop

MCPB を使用して Mailtrap サーバーをインストールします。これらのファイルは Releases にあります。
.MCPB ファイルをダウンロードして開きます。Claude Desktop があれば、開いて設定を提案します。

Claude Desktop または Cursor

以下の設定を追加します：

{
  "mcpServers": {
    "mailtrap": {
      "command": "npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Node.js の管理に asdf を使用している場合は、実行可能ファイルへの絶対パスを使用する必要があります (Mac の例)

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Claude Desktop 設定ファイルの場所

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor 設定ファイルの場所

Mac: ~/.cursor/mcp.json

Windows: %USERPROFILE%\.cursor\mcp.json

VS Code

手動での設定変更

コマンドパレットで実行: Preferences: Open User Settings (JSON)

次に、設定ファイルに以下の設定を追加します：

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "npx",
        "args": ["-y", "mcp-mailtrap"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "[email protected]",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

[!TIP] "env" セクションを変更した後は、MCP サーバーを再起動することを忘れないでください。

MCP Bundle (MCPB)

MCP バンドルをサポートするホストで簡単にインストールするために、.mcpb バンドルファイルを配布できます。

# Build TypeScript and pack the MCPB bundle
npm run mcpb:pack

# Inspect bundle metadata
npm run mcpb:info

# Sign the bundle for distribution (optional)
npm run mcpb:sign

これにより、リポジトリ manifest.json と dist/ のビルド成果物を使用して mailtrap-mcp.mcpb が作成されます。

使用方法

設定が完了すると、エージェントにメールの送信やテンプレートの管理を依頼できます。例：

メール送信操作:

  • "[email protected] に件名 '明日の会議' で、今後の会議についてのリマインダーを送信して。"
  • "[email protected] にプロジェクトの更新についてメールし、[email protected] を CC に入れて。"
  • "ウェルカムテンプレート (uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96) を [email protected] に変数 { name: 'Alex' } で送信して。"
  • "[email protected] に件名 'テストテンプレート' でサンドボックスメールを送信し、ウェルカムメールの見え方をプレビューして。"

メールログ (配信デバッグ):

  • "最近送信したメールログを一覧表示して。"
  • "[email protected] に送信したメールのログを表示して。"
  • "ID abc-123-uuid のメールログメッセージを取得して、配信ステータスを確認して。"

送信統計:

  • "2025年1月の送信統計を取得して。"
  • "先月のドメイン別配信率を表示して。"
  • "2025-01-01 から 2025-01-31 までのカテゴリ別メール統計は？"

サンドボックス操作:

  • "サンドボックスの受信箱からすべてのメッセージを取得して。"
  • "サンドボックスメッセージの最初のページを表示して。"
  • "サンドボックスの受信箱で 'test' を含むメッセージを検索して。"
  • "ID 5159037506 のサンドボックスメッセージの詳細を表示して。"

テンプレート操作:

  • "Mailtrap アカウントのすべてのメールテンプレートを一覧表示して。"
  • "'Welcome Email' という名前で、件名 'Welcome to our platform!' の新しいメールテンプレートを作成して。"
  • "ID 12345 のテンプレートを更新し、件名を 'Updated Welcome Message' に変更して。"
  • "ID 67890 のテンプレートを削除して。"

送信ドメイン:

  • "送信ドメインを一覧表示して。"
  • "ID 3938 の送信ドメインを取得して。"
  • "example.com の送信ドメインを作成して。"
  • "送信ドメイン 3938 を削除して。"
  • "DNS 設定手順を含む送信ドメイン 3938 を取得して。"

利用可能なツール

send-email

Mailtrap を通じてトランザクションメールを送信します。インラインコンテンツ (subject + text/html) または テンプレートベース (template_uuid) の、相互に排他的な2つのモードをサポートします。

パラメータ:

  • from (オプション): メール文字列または { email, name? } としての送信者。指定がない場合、DEFAULT_FROM_EMAIL が使用されます。
  • to (オプション): 受信者 — 単一のメール/{ email, name? } または配列。cc または bcc が指定されている場合はオプション。to / cc / bcc の少なくとも1つに受信者が含まれている必要があります。
  • cc (オプション): CC 受信者の配列 (それぞれメール文字列または { email, name? })。
  • bcc (オプション): BCC 受信者の配列 (それぞれメール文字列または { email, name? })。
  • subject (条件付き): メールの件名。インライン送信には必須。template_uuid が設定されている場合は省略する必要があります。
  • text (条件付き): メール本文テキスト。インライン送信には (html と共に、または代わりに) 必須。template_uuid が設定されている場合は省略する必要があります。
  • html (条件付き): メール本文の HTML バージョン。インライン送信には (text と共に、または代わりに) 必須。template_uuid が設定されている場合は省略する必要があります。
  • category (オプション): 追跡と分析のためのメールカテゴリ。template_uuid が設定されている場合は省略する必要があります。
  • template_uuid (オプション): インラインコンテンツの代わりに Mailtrap メールテンプレートを使用します。設定時、subject / text / html / category は省略する必要があります (Mailtrap API による)。
  • template_variables (オプション): template_uuid で参照されるテンプレートに代入される変数のオブジェクト。template_uuid とのみ併用可能です。

batch-send-transactional-email

1回の Mailtrap API 呼び出しでトランザクションメールのバッチを送信します (デフォルトの送信ストリーム)。共有フィールドは base に、受信者ごとの上書きは requests[] に記述します。各リクエストには、to、cc、または bcc を介して少なくとも1人の受信者を含める必要があります。send-email と同様のインライン vs テンプレートの相互排他 — ベースと各リクエストをマージした後にチェックされます。

パラメータ:

  • base (オプション): バッチ全体で共有されるフィールドを持つオブジェクト。
    • from (オプション): メール文字列または { email, name? } としての送信者。DEFAULT_FROM_EMAIL にフォールバックします。
    • reply_to (オプション): 返信先アドレス。
    • subject / text / html / category (オプション、インラインモード): 各リクエストのデフォルトコンテンツ。
    • template_uuid / template_variables (オプション、テンプレートモード): デフォルトテンプレート + 変数。インラインフィールドとは相互に排他的です。
    • custom_variables (オプション): デフォルトのカスタム変数 (文字列値)。
    • headers (オプション): デフォルトのカスタムヘッダー。
  • requests (必須): 受信者ごとのメッセージの空でない配列。各エントリには以下が含まれます：
    • to (オプション): 受信者 — 文字列、{ email, name? }、または配列。cc または bcc が指定されている場合はオプション。to / cc / bcc の少なくとも1つに受信者が含まれている必要があります。
    • cc, bcc, reply_to (オプション)。
    • インライン (subject/text/html/category) またはテンプレート (template_uuid/template_variables) の上書き。省略されたフィールドは、一致する base の値にフォールバックします。
    • custom_variables, headers (オプション)。

batch-send-bulk-email

Mailtrap のバルクストリーム API を通じてバルクメールのバッチを送信します。batch-send-transactional-email と同じ base + requests[] の形状、検証、インライン vs テンプレートルール — 唯一の違いは、このツールがトランザクションエンドポイントではなくバルクエンドポイントを介して呼び出しをルーティングすることです。上記のパラメータを参照してください。

list-email-logs

オプションのページネーションとフィルターを使用して、送信されたメールログ (配信履歴) を一覧表示します。IDE から配信の問題をデバッグするために使用します。

パラメータ:

  • search_after (オプション): 前のレスポンスの next_page_cursor からのページネーションカーソル
  • sent_after (オプション): ISO 8601 日付/時刻。この時刻以降に送信されたログのみ
  • sent_before (オプション): ISO 8601 日付/時刻。この時刻より前に送信されたログのみ
  • from_email (オプション): 送信者メールでフィルタリング。from_operator と共に使用 (デフォルト: ci_equal)
  • to_email (オプション): 受信者メールでフィルタリング。to_operator と共に使用 (デフォルト: ci_equal)
  • status (オプション): 配信ステータスでフィルタリング: delivered, not_delivered, enqueued, opted_out。status_operator と共に使用 (デフォルト: equal)
  • subject (オプション): メール件名でフィルタリング。subject_operator と共に使用 (デフォルト: ci_contain)。件名の有無でフィルタリングするには subject_operator: empty/not_empty を使用します。
  • sending_domain_id (オプション): 送信ドメイン ID (数値) でフィルタリング。sending_domain_id_operator と共に使用 (デフォルト: equal)
  • sending_stream (オプション): ストリームでフィルタリング: transactional または bulk。sending_stream_operator と共に使用 (デフォルト: equal)
  • events (オプション): イベントタイプでフィルタリング: delivery, open, click, bounce, spam, unsubscribe, soft_bounce, reject, suspension。events_operator (include_event / not_include_event) と共に使用
  • clicks_count / opens_count (オプション): クリック/開封数でフィルタリング。*_operator: equal, greater_than, less_than と共に使用
  • client_ip / sending_ip (オプション): IP でフィルタリング。*_operator: equal, not_equal, contain, not_contain と共に使用
  • email_service_provider_response (オプション): プロバイダの応答テキストでフィルタリング。*_operator (ci_contain など) と共に使用
  • email_service_provider (オプション): プロバイダ (完全一致) でフィルタリング。*_operator: equal, not_equal と共に使用
  • recipient_mx (オプション): 受信者 MX でフィルタリング。recipient_mx_operator (ci_contain など) と共に使用
  • category (オプション): メールカテゴリでフィルタリング。category_operator: equal, not_equal と共に使用

すべてのパラメータはオプションです。

get-email-log-message

ID (UUID) で単一のメールログメッセージを取得します：読みやすいサマリー (from, to, subject, sent time, status, category, stream, engagement, delivery context)、次に詳細なイベント履歴。オプションで、include_content: true を使用すると、Mailtrap が生メッセージ URL を公開している場合に、メッセージ本文 (HTML とプレーンテキスト) を読み込んで表示することもできます。

パラメータ:

  • message_id (必須): メールログメッセージの UUID (送信レスポンスまたは list-email-logs から)。list-email-logs を使用してメッセージ ID を検索します。
  • include_content (オプション): true の場合、生の EML を取得し (raw_message_url が利用可能な場合)、show-sandbox-email-message と同様に、解析された HTML およびプレーンテキストの本文セクションを追加します。

get-sending-stats

日付範囲のメール送信統計 (配信率、バウンス率、開封率、クリック率、スパム率) を取得します。オプションで、ドメイン、カテゴリ、メールサービスプロバイダ、または日付別に分類します。エディタを離れずに配信率を確認できます。

パラメータ:

  • start_date (必須): 統計範囲の開始日 (YYYY-MM-DD)
  • end_date (必須): 統計範囲の終了日 (YYYY-MM-DD)
  • breakdown (任意): 統計の内訳方法: aggregated (デフォルト), by_domain, by_category, by_email_service_provider, または by_date
  • sending_domain_ids (任意): 結果をこれらの送信ドメインIDに制限 (整数の配列)
  • sending_streams (任意): transactional または bulk に制限 (文字列の配列)
  • categories (任意): これらのメールカテゴリに制限 (文字列の配列)
  • email_service_providers (任意): これらのプロバイダーに制限 (例: Google, Yahoo, Outlook) (文字列の配列)

create-template

Mailtrapアカウントに新しいメールテンプレートを作成します。

パラメータ:

  • name (必須): テンプレート名
  • subject (必須): メールの件名
  • html (または text が必須): テンプレートのHTMLコンテンツ
  • text (または html が必須): テンプレートのプレーンテキスト版
  • category (任意): テンプレートカテゴリ (デフォルトは "General")

list-templates

Mailtrapアカウント内のすべてのメールテンプレートを一覧表示します。

パラメータ:

  • パラメータ不要

get-template

IDで単一のメールテンプレートを取得します (件名、カテゴリ、HTML/テキスト本文を含む)。

パラメータ:

  • template_id (必須): 取得するテンプレートのID

update-template

既存のメールテンプレートを更新します。

パラメータ:

  • template_id (必須): 更新するテンプレートのID
  • name (任意): テンプレートの新しい名前
  • subject (任意): 新しいメール件名
  • html (任意): テンプレートの新しいHTMLコンテンツ
  • text (任意): テンプレートの新しいプレーンテキスト版
  • category (任意): テンプレートの新しいカテゴリ

[!NOTE] update-templateを呼び出して更新を実行するには、更新可能なフィールド (name, subject, html, text, category) のうち少なくとも1つを指定する必要があります。

delete-template

既存のメールテンプレートを削除します。

パラメータ:

  • template_id (必須): 削除するテンプレートのID

send-sandbox-email

開発およびテスト目的で、Mailtrapのテスト受信箱にメールを送信します。実際の受信者にメールを送信せずにメールテンプレートをテストするのに最適です。send-email と同じ2つのモード (インラインコンテンツ または テンプレートベース (template_uuid)) をサポートします。

パラメータ:

  • test_inbox_id (任意): Mailtrapテスト受信箱ID。MAILTRAP_TEST_INBOX_ID が設定されていない場合は必須。特定の受信箱を対象とするために呼び出しごとに渡します。
  • from (任意): メール文字列または { email, name? } としての送信者。指定がない場合、DEFAULT_FROM_EMAIL が使用されます。
  • to (任意): カンマ区切り文字列、またはメール文字列 / { email, name? } オブジェクトの配列としての受信者。cc または bcc が指定されている場合は任意。to / cc / bcc のいずれかに受信者を含める必要があります。
  • cc (任意): CC受信者の配列 (各メール文字列または { email, name? })。
  • bcc (任意): BCC受信者の配列 (各メール文字列または { email, name? })。
  • subject (条件付き): メール件名。インライン送信の場合は必須。template_uuid が設定されている場合は省略する必要があります。
  • text (条件付き): メール本文テキスト。インライン送信の場合、html と共に、または代わりに必須。template_uuid が設定されている場合は省略する必要があります。
  • html (条件付き): メール本文のHTMLバージョン。インライン送信の場合、text と共に、または代わりに必須。template_uuid が設定されている場合は省略する必要があります。
  • category (任意): 追跡用のメールカテゴリ。template_uuid が設定されている場合は省略する必要があります。
  • template_uuid (任意): インラインコンテンツの代わりにMailtrapメールテンプレートを使用します。設定する場合、subject / text / html / category は省略する必要があります。
  • template_variables (任意): template_uuid で参照されるテンプレートに代入される変数のオブジェクト。template_uuid と共にのみ使用可能です。

[!NOTE] サンドボックスツールでは、ツール呼び出しで test_inbox_id を指定するか、MAILTRAP_TEST_INBOX_ID 環境変数を設定してください。呼び出しごとに test_inbox_id を渡すことで、受信箱を切り替えることができます。

get-sandbox-messages

Mailtrapテスト受信箱からメッセージのリストを取得します。テスト中にサンドボックスで受信したメールを確認するのに役立ちます。

パラメータ:

  • page (任意): ページネーションのページ番号 (最小: 1)
  • last_id (任意): 最後のメッセージIDを使用したページネーション。指定されたメッセージID以降のメッセージを返します (最小: 1)
  • search (任意): メッセージをフィルタリングするための検索クエリ

[!NOTE] すべてのパラメータは任意です。何も指定しない場合、受信箱の最初のページのメッセージが返されます。従来のページネーションには page を、カーソルベースのページネーションには last_id を、コンテンツによるメッセージのフィルタリングには search を使用します。

show-sandbox-email-message

Mailtrapテスト受信箱から特定のメールメッセージの詳細情報とコンテンツ (HTMLおよびテキスト本文を含む) を表示します。

パラメータ:

  • message_id (必須): 取得するサンドボックスメールメッセージのID

[!NOTE] 最初に get-sandbox-messages を使用してメッセージとそのIDのリストを取得し、次にこのツールを使用して特定のメッセージの完全なコンテンツを表示します。

get-sandbox-project

IDでサンドボックスプロジェクトを取得します (受信箱とメール数を含む)。

パラメータ:

  • project_id (必須): 取得するプロジェクトのID

update-sandbox-project

既存のサンドボックスプロジェクトの名前を変更します。

パラメータ:

  • project_id (必須): 更新するプロジェクトのID
  • name (必須): プロジェクトの新しい名前 (2～100文字)

list-sandboxes

APIトークンがアクセス可能なすべてのサンドボックスを全プロジェクトにわたって一覧表示します。

パラメータ:

  • パラメータ不要

mark-sandbox-as-read

サンドボックス内のすべてのメッセージを既読にします。

パラメータ:

  • sandbox_id (必須): 操作対象のサンドボックスID

reset-sandbox-credentials

サンドボックスのSMTP認証情報をリセットします。新しいユーザー名/パスワードを返します。

パラメータ:

  • sandbox_id (必須): 操作対象のサンドボックスID

enable-sandbox-email-address

サンドボックスのメール受信アドレスを有効にします (SMTP経由でサンドボックスにメッセージを配信するMailtrapアドレスをオンにします)。

パラメータ:

  • sandbox_id (必須): 操作対象のサンドボックスID

reset-sandbox-email-address

サンドボックスの新しいメール受信アドレスを生成します。

パラメータ:

  • sandbox_id (必須): 操作対象のサンドボックスID

forward-sandbox-message

サンドボックスメッセージを外部メールアドレスに転送します。月間転送クォータにカウントされます。

パラメータ:

  • sandbox_id (任意): サンドボックスID。MAILTRAP_SANDBOX_ID にフォールバックします。
  • message_id (必須): 転送するサンドボックスメッセージのID
  • email (必須): メッセージの転送先メールアドレス

update-sandbox-message

サンドボックスメッセージを既読または未読にします。

パラメータ:

  • sandbox_id (任意): サンドボックスID。MAILTRAP_SANDBOX_ID にフォールバックします。
  • message_id (必須): 更新するサンドボックスメッセージのID
  • is_read (必須): true は既読、false は未読にします

delete-sandbox-message

単一のサンドボックスメッセージを削除します。

パラメータ:

  • sandbox_id (任意): サンドボックスID。MAILTRAP_SANDBOX_ID にフォールバックします。
  • message_id (必須): 削除するサンドボックスメッセージのID

get-sandbox-message-spam-score

サンドボックスメッセージのSpamAssassinスパムレポート (スコア、ルール、完全なレポート) を取得します。show-sandbox-email-message の include_spam_report: true のスタンドアロン代替手段です。

パラメータ:

  • sandbox_id (任意): サンドボックスID。MAILTRAP_SANDBOX_ID にフォールバックします。
  • message_id (必須): サンドボックスメッセージのID

get-sandbox-message-html-analysis

サンドボックスメッセージのHTML分析レポート (クライアント互換性スコア、問題のある要素) を取得します。show-sandbox-email-message の include_html_analysis: true のスタンドアロン代替手段です。

パラメータ:

  • sandbox_id (任意): サンドボックスID。MAILTRAP_SANDBOX_ID にフォールバックします。
  • message_id (必須): サンドボックスメッセージのID

get-sandbox-message-headers

サンドボックスメッセージの解析済みメールヘッダーを取得します。

パラメータ:

  • sandbox_id (任意): サンドボックスID。MAILTRAP_SANDBOX_ID にフォールバックします。
  • message_id (必須): サンドボックスメッセージのID

get-sandbox-message-html

サンドボックスメッセージのレンダリングされたHTML本文を取得します。

パラメータ:

  • sandbox_id (任意): サンドボックスID。MAILTRAP_SANDBOX_ID にフォールバックします。
  • message_id (必須): サンドボックスメッセージのID

get-sandbox-message-text

サンドボックスメッセージのプレーンテキスト本文を取得します。

パラメータ:

  • sandbox_id (任意): サンドボックスID。MAILTRAP_SANDBOX_ID にフォールバックします。
  • message_id (必須): サンドボックスメッセージのID

get-sandbox-message-raw

サンドボックスメッセージの生のMIME形式メッセージ (ヘッダー + 本文) を取得します。

パラメータ:

  • sandbox_id (任意): サンドボックスID。MAILTRAP_SANDBOX_ID にフォールバックします。
  • message_id (必須): サンドボックスメッセージのID

get-sandbox-message-eml

EMLファイルペイロードとしてレンダリングされたメッセージを取得します (チケットへの添付や別のメールクライアントへのインポートに適しています)。

パラメータ:

  • sandbox_id (任意): サンドボックスID。MAILTRAP_SANDBOX_ID にフォールバックします。
  • message_id (必須): サンドボックスメッセージのID

get-sandbox-message-html-source

サンドボックスメッセージのレンダリング前のHTMLソース (CIDリンクの書き換えなど、Mailtrap側の変換が行われる前のHTML) を取得します。

パラメータ:

  • sandbox_id (任意): サンドボックスID。MAILTRAP_SANDBOX_ID にフォールバックします。
  • message_id (必須): サンドボックスメッセージのID

list-sandbox-attachments

サンドボックスメッセージのすべての添付ファイル (ファイル名、コンテンツタイプ、サイズ、ダウンロードパス) を一覧表示します。

パラメータ:

  • sandbox_id (任意): サンドボックスID。MAILTRAP_SANDBOX_ID にフォールバックします。
  • message_id (必須): サンドボックスメッセージのID

get-sandbox-attachment

単一の添付ファイルのメタデータとダウンロードURLを取得します。

パラメータ:

  • sandbox_id (任意): サンドボックスID。MAILTRAP_SANDBOX_ID にフォールバックします。
  • message_id (必須): 添付ファイルを含むサンドボックスメッセージのID
  • attachment_id (必須): 取得する添付ファイルのID

list-sending-domains

送信ドメインとそのDNS検証ステータスを一覧表示します。

パラメータ:

  • パラメータ不要

get-sending-domain

IDで送信ドメインとその検証ステータス (DNSレコードを含む) を取得します。include_setup_instructions を true に設定すると、オプションでDNSセットアップ手順を含めることができます。

パラメータ:

  • sending_domain_id (必須): 送信ドメインID
  • include_setup_instructions (任意): true の場合、DNSセットアップ手順をレスポンスに追加します。デフォルト: false

create-sending-domain

新しい送信ドメインを作成します。作成後、DNSレコードを追加してドメインを検証します (レコードを確認するには、include_setup_instructions: true を指定して get-sending-domain を使用します)。

パラメータ:

  • domain_name (必須): ドメイン名 (例: example.com)

delete-sending-domain

送信ドメインを削除します。

パラメータ:

  • sending_domain_id (必須): 削除する送信ドメインID

send-sending-domain-setup-instructions

送信ドメインのDNSセットアップ手順を指定されたアドレスにメールで送信します。DevOpsチームメイトにDNSレコードを転送するのに役立ちます。

パラメータ:

  • sending_domain_id (必須): 送信ドメインID
  • email (必須): DNSセットアップ手順の送信先メールアドレス

list-suppressions

抑制リスト (ハードバウンス、スパム苦情、購読解除、手動インポート) を一覧表示または検索します。1回の呼び出しで最大1000件の結果を返します。

パラメータ:

  • email (オプション): メールフィルター。このアドレスに一致する抑制のみを返します。

delete-suppression

IDで抑制を削除します。Mailtrapは、再度抑制されない限り、このメールアドレスへの配信を再開します。

パラメータ:

  • suppression_id (必須): 削除する抑制のID

list-webhooks

アカウントに設定されているすべてのWebhookを一覧表示します。完全なWebhookレコードをJSONで返します。

パラメータ:

  • パラメータは不要です

get-webhook

IDで単一のWebhookを取得します。完全なWebhookレコードをJSONで返します。注意: signing_secret はここでは返されません。これは create-webhook からのレスポンスでのみ利用可能です。

パラメータ:

  • webhook_id (必須): 取得するWebhookのID

create-webhook

Webhookを作成します。レスポンスには、Webhookペイロードの署名を検証するための signing_secret が含まれます。このシークレットは作成時にのみ返されるため、すぐに保存してください。紛失した場合は、Webhookを再作成してください。

パラメータ:

  • url (必須): MailtrapがWebhookイベントをPOSTするURL
  • webhook_type (必須): "email_sending" または "audit_log"
  • active (オプション、ブール値): デフォルトは true
  • payload_format (オプション): "json" または "jsonlines"。デフォルトは "json"
  • sending_stream (オプション、email_sending のみ): "transactional" または "bulk"
  • event_types (オプション、email_sending のみ): delivery、soft_bounce、bounce、suspension、unsubscribe、open、spam_complaint、click、reject の配列
  • domain_id (オプション、email_sending のみ): このWebhookのスコープを設定する送信ドメインID

update-webhook

Webhookの変更可能なフィールドを更新します。webhook_type、sending_stream、domain_id は作成後に変更できません。これらを変更する必要がある場合は、Webhookを再作成してください。

パラメータ:

  • webhook_id (必須): 更新するWebhookのID
  • url (オプション): 新しいWebhook URL
  • active (オプション、ブール値): Webhookを有効または無効にする
  • payload_format (オプション): "json" または "jsonlines"
  • event_types (オプション、email_sending のみ): delivery、soft_bounce、bounce、suspension、unsubscribe、open、spam_complaint、click、reject の配列

delete-webhook

IDでWebhookを完全に削除します。削除されたWebhookレコードを返します。

パラメータ:

  • webhook_id (必須): 削除するWebhookのID

get-contact

IDまたはメールアドレスで連絡先を取得します。完全な連絡先レコード（リストメンバーシップ、ステータス、カスタムフィールド）を返します。

パラメータ:

  • contact_identifier (必須): 連絡先IDまたはメールアドレス

create-contact

新しい連絡先を作成します。

パラメータ:

  • email (必須): メールアドレス
  • fields (オプション): マージタグでキー設定されたカスタムフィールド値（例: first_name）。文字列、数値、またはブール値
  • list_ids (オプション): この連絡先を登録する連絡先リストのID
  • unsubscribed (オプション、ブール値): unsubscribed ステータスで連絡先を作成する

update-contact

IDまたはメールアドレスで識別される既存の連絡先を更新します。list_ids は連絡先の完全なメンバーシップセットを置き換えます。list_ids_included/list_ids_excluded は、残りを変更せずに追加/削除します。

パラメータ:

  • contact_identifier (必須): 連絡先IDまたはメールアドレス
  • email (オプション): 新しいメールアドレス
  • fields (オプション): マージタグでキー設定されたカスタムフィールド値
  • list_ids (オプション): メンバーシップセットをこの正確なリストで置き換える
  • list_ids_included (オプション): 追加するリストID（加算的）
  • list_ids_excluded (オプション): 削除するリストID
  • unsubscribed (オプション、ブール値): unsubscribed (true) または subscribed (false) に設定

delete-contact

IDまたはメールアドレスで連絡先を完全に削除します。APIが削除された連絡先レコードを返す場合はそれを返し、そうでない場合は確認ペイロードを返します。

パラメータ:

  • contact_identifier (必須): 連絡先IDまたはメールアドレス

create-contact-event

連絡先（IDまたはメールアドレス）に対して連絡先イベントを記録します。連絡先リストの自動化をトリガーするために使用されます。

パラメータ:

  • contact_identifier (必須): 連絡先IDまたはメールアドレス
  • name (必須): イベント名（自動化トリガーと一致）
  • params (必須): 任意のキー/値ペアのオブジェクト。値は文字列、数値、ブール値、またはnull

list-contact-lists

アカウントのすべての連絡先リストを一覧表示します。

パラメータ:

  • パラメータは不要です

get-contact-list

IDで連絡先リストを取得します。

パラメータ:

  • list_id (必須): 取得する連絡先リストのID

create-contact-list

新しい連絡先リストを作成します。

パラメータ:

  • name (必須): 新しいリストの名前

update-contact-list

既存の連絡先リストの名前を変更します。

パラメータ:

  • list_id (必須): 連絡先リストのID
  • name (必須): リストの新しい名前

delete-contact-list

IDで連絡先リストを完全に削除します。

パラメータ:

  • list_id (必須): 削除する連絡先リストのID

list-contact-fields

アカウントのすべての連絡先フィールド定義を一覧表示します。

パラメータ:

  • パラメータは不要です

get-contact-field

IDで連絡先フィールド定義を取得します。

パラメータ:

  • field_id (必須): 連絡先フィールドのID

create-contact-field

新しい連絡先フィールド定義を作成します。merge_tag はアカウント内で一意である必要があり、テンプレート変数のプレースホルダー名として使用されます。

パラメータ:

  • name (必須): 表示名（例: "First Name"）
  • merge_tag (必須): 一意のプレースホルダー名（例: first_name）
  • data_type (必須): text、number、boolean、date のいずれか

update-contact-field

連絡先フィールド定義を更新します。name、merge_tag、data_type の任意の組み合わせを変更できます。

パラメータ:

  • field_id (必須): 連絡先フィールドのID
  • name (オプション): 新しい表示名
  • merge_tag (オプション): 新しいマージタグ（一意である必要があります）
  • data_type (オプション): text、number、boolean、date のいずれか

delete-contact-field

IDで連絡先フィールド定義を完全に削除します。

パラメータ:

  • field_id (必須): 削除する連絡先フィールドのID

create-contact-import

連絡先を一括インポートします。インポートジョブレコードを返します。get-contact-import でそのステータスをポーリングします。

パラメータ:

  • contacts (必須): 連絡先エントリの配列。各エントリには以下が必要です:
    • email (必須): 連絡先のメールアドレス
    • fields (オプション): マージタグでキー設定されたカスタムフィールド値（文字列または数値）
    • list_ids_included (オプション): 連絡先を追加するリストID
    • list_ids_excluded (オプション): 連絡先を削除するリストID

get-contact-import

連絡先インポートジョブのステータス（作成済み/開始済み/完了/失敗）を、作成/更新/上限超過のカウントとともに取得します。

パラメータ:

  • import_id (必須): 連絡先インポートジョブのID

create-contact-export

AND結合された一連のフィルターに一致する連絡先をエクスポートします。エクスポートジョブレコードを返します。status が finished になったら、get-contact-export でステータスをポーリングしてダウンロードURLを取得します。

パラメータ:

  • filters (必須): フィルターオブジェクトの配列。各オブジェクトには以下があります:
    • name (必須): フィルター対象のフィールド（list_id、subscription_status、email など）
    • operator (必須): equal、not_equal、contains、not_contains、is_empty、is_not_empty のいずれか
    • value (必須): 比較値（文字列、数値、ブール値、または配列）

get-contact-export

連絡先エクスポートジョブのステータスを取得します。status が finished になると、url フィールドにCSVダウンロードリンクが保持されます。

パラメータ:

  • export_id (必須): 連絡先エクスポートジョブのID

list-accounts

現在のAPIトークンがアクセスできるMailtrapアカウントを、各アカウントのアクセスレベルとともに一覧表示します。

パラメータ:

  • パラメータは不要です

get-billing-usage

アカウントの現在の請求サイクルの使用状況（送信プランとテストプラン、制限、現在のカウント）を取得します。

パラメータ:

  • パラメータは不要です

list-account-accesses

アカウントのアカウントアクセス（ユーザー、招待、APIトークン）を一覧表示します。オプションのフィルターで結果を特定のリソースに絞り込みます。アカウント管理者/所有者の権限が必要です。

パラメータ:

  • domain_uuids (オプション): 送信ドメインUUIDでフィルター（文字列の配列）
  • inbox_ids (オプション): サンドボックス受信箱IDでフィルター（文字列の配列）
  • project_ids (オプション): サンドボックスプロジェクトIDでフィルター（文字列の配列）

remove-account-access

IDでアカウントアクセスを削除します。User 指定子の場合、権限が取り消されます。Invite または ApiToken 指定子の場合、指定子が完全に削除されます。管理者/所有者が必要です。

パラメータ:

  • account_access_id (必須): 削除するアクセスレコードのID

get-permission-resources

APIトークンが管理者アクセス権を持つすべてのリソース（受信箱、プロジェクト、ドメイン、請求、アカウント）を、階層別にネストして取得します。

パラメータ:

  • パラメータは不要です

bulk-update-permissions

単一のアカウントアクセスに対する権限を一括で作成、更新、または破棄します。既存の (resource_type, resource_id) ペアは更新され、新しいペアは作成されます。エントリに destroy: true を設定すると削除されます。

パラメータ:

  • account_access_id (必須): 対象のアカウントアクセスID
  • permissions (必須): 権限エントリの配列。各エントリには以下があります:
    • resource_id (必須): リソースID（数値または文字列）
    • resource_type (必須): account、project、inbox、domain、billing のいずれか
    • access_level (オプション): admin/100 または viewer/10
    • destroy (オプション、ブール値): trueの場合、この権限を作成/更新する代わりに削除します

list-api-tokens

アカウントのすべてのAPIトークンを一覧表示します。

パラメータ:

  • パラメータは不要です

create-api-token

新しいAPIトークンを作成します。レスポンスにはシークレット token 値が含まれます。これは完全なトークンが返される唯一のタイミングであるため、すぐに保存してください。紛失した場合は、トークンを再作成してください。

パラメータ:

  • name (必須): トークンの表示名
  • resources (オプション): トークンのスコープを設定するリソース権限の配列。各エントリには以下があります:
    • resource_type (必須): account、project、inbox、domain、billing のいずれか
    • resource_id (必須): リソースのID
    • access_level (必須): 100 (管理者) または 10 (閲覧者)

get-api-token

IDでAPIトークンを取得します。メタデータのみを返します。シークレットトークン値はここでは返されません（create-api-token / reset-api-token からのみ）。

パラメータ:

  • api_token_id (必須): APIトークンのID

reset-api-token

IDでAPIトークンをリセット（ローテーション）します。レスポンスには新しいシークレット token 値が含まれます。この呼び出しでのみ返されるため、すぐに保存してください。以前のトークンは無効になります。

パラメータ:

  • api_token_id (必須): リセットするAPIトークンのID

delete-api-token

IDでAPIトークンを完全に削除します。削除後、トークンは認証に使用できなくなります。

パラメータ:

  • api_token_id (必須): 削除するAPIトークンのID

list-sub-accounts

組織内のサブアカウントを一覧表示します。MAILTRAP_ORGANIZATION_ID 環境変数とサブアカウント管理権限が必要です。

パラメータ:

  • パラメータは不要です

create-sub-account

組織の下に新しいサブアカウントを作成します。MAILTRAP_ORGANIZATION_ID 環境変数とサブアカウント管理権限が必要です。

パラメータ:

  • name (必須): 新しいサブアカウントの表示名

開発

  1. リポジトリをクローンします:
git clone https://github.com/mailtrap/mailtrap-mcp.git
cd mailtrap-mcp
  1. 依存関係をインストールします:
npm install

Claude Desktop または Cursor での設定

[!TIP] 設定ファイルの場所については セットアップ セクションを参照してください。

以下の設定を追加します:

{
  "mcpServers": {
    "mailtrap": {
      "command": "node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Node.js の管理に asdf を使用している場合は、実行可能ファイルへの絶対パスを使用する必要があります:

(Mac の例)

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

VS Code

[!TIP] 設定ファイルの場所については セットアップ セクションを参照してください。

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "node",
        "args": ["/path/to/mailtrap-mcp/dist/index.js"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "[email protected]",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

テスト

実際の Mailtrap に対するツールの実行

実際の Mailtrap アカウントに対してツールをエンドツーエンドで実行する方法は2つあります。インタラクティブな探索のための MCP Inspector ブラウザ UI と、シェルからのワンショット呼び出しのための CLI モードです。

どちらも最初にバンドルをビルドする必要があります:

npm run build

そして、シェルで MAILTRAP_API_TOKEN と MAILTRAP_ACCOUNT_ID をエクスポートします (mcp:cli スクリプトが両方を生成されたサーバーに転送します)。

ブラウザ UI

npm run dev

Inspector は http://localhost:6274 のような URL を表示します。それを開き、ツール タブに切り替え、ツール (例: get-template) を選択し、パラメータを JSON として入力し、実行 をクリックします。Mailtrap の応答が下のパネルに表示されます。

CLI

UI なしのワンショット呼び出しには npm run mcp:cli を使用します。Inspector の CLI フラグを -- の後に渡すと、npm がそれらをそのまま転送します:

# List all tools
npm run mcp:cli -- --method tools/list

# Call a tool — flags after the `--`
npm run mcp:cli -- \
  --method tools/call \
  --tool-name get-template \
  --tool-arg template_id=12345

# Multiple --tool-arg flags for tools with several params
npm run mcp:cli -- \
  --method tools/call \
  --tool-name send-sending-domain-setup-instructions \
  --tool-arg sending_domain_id=3938 \
  --tool-arg [email protected]

MCPB サーバーの実行

# Run the MCPB server directly
node dist/mcpb-server.js

# Or use the provided binary
mailtrap-mcpb-server

[!TIP] MCP Inspector を使用した開発の場合:

npm run dev:mcpb

エラー処理

このサーバーは MCP の規則に沿った構造化エラー処理を使用します:

  • VALIDATION_ERROR: 入力検証エラー
  • CONFIGURATION_ERROR: 設定の欠落または無効
  • EXECUTION_ERROR: ランタイム実行エラー
  • TIMEOUT: 操作のタイムアウト (デフォルト 30 秒)

エラーには実行可能なメッセージが含まれ、構造化された形式でログに記録されます。

セキュリティ

  • Zod スキーマによる入力検証
  • 環境変数の安全な処理
  • 操作のタイムアウト保護 (30 秒)
  • エラー出力での機密詳細のサニタイズ

ログ記録

INFO、WARN、ERROR、DEBUG のレベルを持つ構造化 JSON ログ。

DEBUG=true を設定してデバッグログを有効にします。

# Example: enable debug logging
DEBUG=true node dist/mcpb-server.js

重要: サーバーはログを stderr に書き込むため、stdout は JSON-RPC フレーム用に予約されたままになります。これにより、ログが混在することによる JSON 解析エラーがホストで発生するのを防ぎます。

jq を使用したログ分析の例:

# Filter error logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "error")'

# Filter debug logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "debug")'

トラブルシューティング

よくある問題:

  1. API トークンがない: MAILTRAP_API_TOKEN が設定されていることを確認してください
  2. サンドボックスが機能しない: ツール呼び出しで test_inbox_id を提供するか、MAILTRAP_TEST_INBOX_ID 環境変数を設定してください
  3. タイムアウトエラー: ネットワーク接続と Mailtrap API のステータスを確認してください
  4. 検証エラー: すべての必須フィールドが提供されていることを確認してください

貢献

バグレポートとプルリクエストは GitHub で歓迎します。このプロジェクトは安全で歓迎的なコラボレーションの場であることを意図しており、貢献者は 行動規範 に従うことが期待されます。

ライセンス

このパッケージは MIT ライセンス の条件の下でオープンソースとして利用可能です。

行動規範

Mailtrap プロジェクトのコードベース、Issue トラッカー、チャットルーム、メーリングリストでやり取りするすべての人は、行動規範 に従うことが期待されます。