Mailgun MCP Server

Mailgun MCP サーバー

概要

Mailgun 向けの Model Context Protocol（MCP）サーバーです。AI エージェントに、メールの送信、配信状況の診断、アカウント操作の管理を行うための、実用的でワークフロー指向のインターフェースを提供します。

メモ

この MCP サーバーはお使いのマシン上でローカルに実行され、stdio 経由で通信します。Mailgun は現在、このサーバーのホスト版を提供していません。

機能

• メッセージング — メールの送信、保存済みメッセージの取得、メッセージの再送信
• ドメイン — ドメインの詳細表示、DNS 設定の検証、トラッキング設定（クリック、開封、配信停止）の管理
• Webhook — イベント Webhook の一覧表示、作成、更新
• ルート — 受信メールのルーティングルールの表示と更新
• メーリングリスト — メーリングリストとメンバーの作成、表示、更新
• テンプレート — バージョン管理付きメールテンプレートの作成、表示、更新
• 分析 — 送信指標、使用状況指標、ログの照会
• 統計 — ドメイン、タグ、プロバイダー、デバイス、国別の集計統計の表示
• 抑制リスト — バウンス、配信停止、苦情、許可リストの項目の表示
• IP と IP プール — IP の割り当てと専用 IP プール設定の表示
• バウンス分類 — バウンスの種類と配信の問題の分析
• 検証 — 送信前にメールアドレスの配信可能性と構文を検証（validate）
• 最適化（受信トレイへの配置） — 配信可能性を評価するために、受信トレイへの配置／シードテストの結果を取得（optimize）
• 検査（メールプレビュー） — クライアント間でのメールのレンダリングとプレビューテストの結果を取得（inspect）
• アカウント上限 — カスタムの月間送信上限を表示

上記の括弧内のラベル（validate、optimize、inspect）は、タグによるフィルタリングで使用される製品タグです。それ以外のすべての機能は、send タグで登録されます。

メモ

ツールは読み取り操作と更新操作に限定されており、削除操作は公開されません。これにより、意図しない操作の影響範囲を小さくできます。セキュリティに関する考慮事項を参照してください。

仕組み

このサーバーは OpenAPI 主導で動作します。起動時に同梱された Mailgun OpenAPI 仕様を解析し、厳選された許可リストのエンドポイントを MCP ツールとして登録します。各ツールの入力スキーマは、仕様から Zod を使って生成されます。すべてのツールには Mailgun の製品タグ（send、validate、optimize、inspect）が注釈として付けられます。一致するすべてのツールは起動時に登録されます。遅延読み込みやオンデマンド読み込みはありません。タグによるフィルタリングは起動時に適用され、登録するツールを絞り込むため、ワークフローごとに必要な製品だけを公開できます。

前提条件

• Node.js（v20.12 以降）
• Mailgun アカウントと API キー

インストール

このサーバーは @mailgun/mcp-server として npm で公開されており、stdio 経由で実行されます。多くのクライアントでは npx を使って必要に応じて起動できるため、グローバルにインストールする必要はありません。以下の各スニペットでは、YOUR-mailgun-api-key をMailgun API セキュリティ設定で取得したキーに置き換えてください。

ヒント

アカウントが Mailgun の EU リージョンでホストされている場合は、env ブロックに "MAILGUN_API_REGION": "eu" を追加してください（または CLI で -e MAILGUN_API_REGION=eu を指定します）。デフォルトは us です。

Claude Code

claude mcp add mailgun -e MAILGUN_API_KEY=YOUR-mailgun-api-key -- npx -y @mailgun/mcp-server

その後、Claude Code で /mcp を実行し、mailgun サーバーが接続されていることを確認してください。

Claude Desktop

Settings → Developer → Edit Config を開くか、ファイルを直接編集してください。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key",
        "MAILGUN_API_REGION": "us"
      }
    }
  }
}

Cursor

コマンドパレットを開き、Cursor Settings → MCP → Add new global MCP server を選択して、以下を追加します。

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

Codex

codex mcp add mailgun \
  --env MAILGUN_API_KEY=YOUR-mailgun-api-key \
  -- npx -y @mailgun/mcp-server

VS Code (GitHub Copilot)

以下を settings.json に追加します。

{
  "mcp": {
    "servers": {
      "mailgun": {
        "command": "npx",
        "args": ["-y", "@mailgun/mcp-server"],
        "env": {
          "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
        }
      }
    }
  }
}

Windsurf

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

Gemini CLI

~/.gemini/settings.json に追加します。

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

設定

環境変数

変数	必須	デフォルト	説明
MAILGUN_API_KEY	はい	—	Mailgun API キー
MAILGUN_API_REGION	いいえ	us	API リージョン：us または eu
MAILGUN_API_HOSTNAME	いいえ	（リージョンから導出）	API ホスト名を上書きします（例：api.eu.mailgun.net）。リージョンより優先されます。
MAILGUN_MCP_TAGS	いいえ	（すべて）	有効にする製品タグをカンマ区切りで指定します。--tags と同等です。CLI フラグが優先されます。

CLI オプション

クライアントの args でパッケージ名の後にフラグを渡します（例：["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"]）。

フラグ	説明
--tags <list>	有効にする製品タグをカンマ区切りで指定します（デフォルト：すべて）。有効な値：send、validate、optimize、inspect。
--list-tags	有効なタグの値を表示して終了します。
--help、-h	使用方法を表示して終了します。

タグによるフィルタリング

サーバーが登録するツールを、1 つ以上の Mailgun 製品タグに絞り込めます。モデルに表示するツールセットを限定するのに便利です。たとえば、送信機能を必要としないワークフローでは、検証ツールのみを公開できます。

有効なタグ：send、validate、optimize、inspect。指定しない場合は、すべてのツールが登録されます（現時点でのデフォルト）。

フィルタリングには OR セマンティクス が使用されます。有効なタグのいずれかがツールのタグに含まれていれば、そのツールは登録されます。

CLI フラグを使用する場合 — MCP クライアント設定の args に --tags を指定します。

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

環境変数を使用する場合 — MAILGUN_MCP_TAGS を設定します（両方が指定されている場合は CLI フラグが優先されます）。

"env": {
  "MAILGUN_API_KEY": "YOUR-mailgun-api-key",
  "MAILGUN_MCP_TAGS": "validate,inspect"
}

ヒント

バイナリを --list-tags 付きで実行すると、サポートされているタグの値が表示されます。すべての使用方法を確認するには --help を指定してください。不明なタグは起動時に明確なエラーメッセージとともに拒否されます。

プロンプトの例

メールを送信する

Can you send an email to EMAIL_HERE with a funny email body that makes it sound
like it's from the IT Desk from Office Space? Please use the sending domain
DOMAIN_HERE, and make the email from "postmaster@DOMAIN_HERE"!

メモ

データを送信するツールを呼び出すには、有料プランが必要な MCP クライアントもあります。送信がエラーもなく失敗する場合は、クライアントのプランを確認してください。

送信統計を取得して可視化する

Would you be able to make a chart with email delivery statistics for the past week?

テンプレートを管理する

Create a welcome email template for new signups on my domain DOMAIN_HERE.
Include a personalized greeting and a call-to-action button.

配信可能性を調査する

Can you check the bounce classification stats for my account and tell me
what the most common bounce reasons are?

DNS の問題を解決する

Check the DNS verification status for my domain DOMAIN_HERE and tell me
if anything needs fixing.

抑制リストを確認する

Are there any unsubscribes or complaints for DOMAIN_HERE? Summarize the
top offenders.

ルーティングルールを管理する

List all my inbound routes and explain what each one does.

メーリングリストを作成する

Create a mailing list called announcements@DOMAIN_HERE and add these
members: [email protected], [email protected].

ドメインを比較する

Compare my sending volume and delivery rates across all my domains for
the past month.

地域別のエンゲージメント

Break down my email engagement by country and device for DOMAIN_HERE.

トラッキング設定を確認する

List all my domains and show which ones have tracking enabled for clicks
and opens.

メールアドレスを検証する

Validate the email address EMAIL_HERE and tell me whether it's safe to send to.

受信トレイへの配置を確認する（Optimize）

Pull the inbox placement results for seed test RESULT_ID_HERE and summarize
where my message landed (inbox, spam, or missing) by provider.

メールをプレビューする（Inspect）

Get the email preview results for test TEST_ID_HERE and tell me if the email
renders correctly across clients.

開発

ソースから実行する

サーバーは TypeScript で記述されています。クローン、インストール、ビルド、テストを行います。

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

npm run build は src/ を dist/ にコンパイルし、バンドルされた OpenAPI 仕様をコピーします。npx の代わりにビルド済みエントリを MCP クライアントに指定します（絶対パスを使用してください）。

{
  "mcpServers": {
    "mailgun": {
      "command": "node",
      "args": ["/absolute/path/to/mailgun-mcp-server/dist/mailgun-mcp.js"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

編集しながらのライブテスト

MCP サーバーは長時間実行される stdio プロセスであり、ホットリロードには対応していません。そのため、保存時にビルドし、変更を反映するためにクライアントを再接続する流れになります。

1. dist/openapi.yaml を用意するため、最初に npm run build を実行します。

2. TypeScript コンパイラーを起動したままにして、保存するたびに dist/ を再ビルドします。

   npx tsc --watch
   

3. 別の MCP クライアント（または下記の MCP Inspector）から dist/mailgun-mcp.js に接続します。変更後は、MCP クライアントのセッションを再起動して新しいビルドを読み込みます。

MCP Inspector を使ったテスト

MCP Inspector を使うと、完全なクライアントを用意しなくてもツールを実行できます。まずビルドし、その後、ビルド済みのサーバーに対して起動します。

npm run build
MAILGUN_API_KEY=YOUR-mailgun-api-key npx @modelcontextprotocol/inspector node dist/mailgun-mcp.js

Inspector UI を開いて Connect をクリックし、次に List Tools を使ってサーバーが動作していることを確認します。フィルターされたツールセットをテストするには、サーバーのパスの後にフラグを追加します。

MAILGUN_API_KEY=YOUR-mailgun-api-key npx @modelcontextprotocol/inspector node dist/mailgun-mcp.js --tags validate,inspect

コミット前フック

npm install を実行すると、ステージングされた TypeScript/JavaScript ファイルに対して oxlint --fix と oxfmt を実行し、npm run check:versions も実行する Git のコミット前フック（husky 経由）がインストールされます。修正可能な問題は自動で修正され、再度ステージングされます。修正できない lint エラーやバージョン同期の不一致を含むコミットは拒否されます。この変更より前にローカルクローンを作成していた場合は、フックをインストールするために npm install を一度実行してください。

エンドポイントの追加に関する注意

新しいエンドポイントを追加する際、定義に単純な文字列を使用すると、_meta フィールドでデフォルトのプロダクト種別 send がタグ付けされます。別のプロダクトとしてタグ付けする場合は、EndpointEntry 型のオブジェクト形式を使用してください。

セキュリティに関する考慮事項

API キーの隔離

Mailgun API キーは環境変数として渡され、AI モデル自体に公開されることはありません。認証のために MCP サーバープロセスだけが使用します。サーバーは API キー、リクエストパラメーター、レスポンスデータをログに記録しません。

ローカルでの実行

サーバーはお使いのマシン上でローカルに実行されます。Mailgun API との通信はすべて、TLS 証明書の検証を適用した HTTPS 経由で行われます。Mailgun API 以外のサードパーティサービスにデータが送信されることはありません。

API キーの権限

必要な操作だけに権限を限定した、専用の Mailgun API キーを使用してください。サーバーは読み取り操作と更新操作を公開しますが、削除操作は公開しません。これにより、意図しない操作による影響範囲を限定できます。

レート制限

サーバーはクライアント側のレート制限を実装していません。AI からの各ツール呼び出しは、Mailgun API へのリクエストに直接変換されます。サーバーは不正利用を防ぐため、Mailgun 側のレート制限に依存しています。制限を超えたリクエストは、AI アシスタントにエラーを返します。

プロンプトインジェクション

他の MCP サーバーと同様に、巧妙に作られたプロンプトや敵対的なプロンプトによって、AI アシスタントが意図しない操作を呼び出すよう誘導される可能性があります。たとえば、トラッキング設定の変更やメーリングリストメンバーの読み取りなどです。特に信頼できないプロンプトのコンテキストでは、操作を承認する前に AI アシスタントのツール呼び出しの確認内容を確認してください。

Webhook URL

Webhook の作成および更新操作では、AI アシスタントを介して任意の URL を指定できます。MCP サーバーは追加の検証を行わず、これらの URL を Mailgun API に渡します。Webhook の送信先の検証は Mailgun が行います。AI アシスタントが、意図しない内部アドレスや機密性の高いアドレスを Webhook URL に設定しないようにしてください。

入力検証

すべてのツールパラメーターは、Zod スキーマを使用して Mailgun OpenAPI 仕様に照らして検証されます。ただし、検証の精度は OpenAPI 仕様の正確さに依存し、一部の特殊なパラメーターでは許容的な検証にフォールバックすることがあります。追加の保護層として、Mailgun API でも独自のサーバー側検証が行われます。

デバッグ

MCP サーバーは stdio 経由で通信します。トラブルシューティングについては、MCP デバッグガイドを参照してください。

ライセンス

Apache 2.0 — 詳細はLICENSEをご覧ください。

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信するか、イシューを作成してください。