Mailgun

Mailgun MCP Server

概要

Model Context Protocol (MCP) サーバー for Mailgun で、AIエージェントにメール送信、到達性診断、アカウント操作管理のための実用的なワークフロー指向インターフェースを提供します。

[!NOTE] このMCPサーバーはローカルマシン上で動作し、標準入出力(stdio)経由で通信します。Mailgunは現在、このサーバーのホスト版を提供していません。

機能

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

上記の括弧内ラベル (validate, optimize, inspect) は、タグフィルタリングで使用される製品タグです。その他の機能はすべて send タグで登録されます。

[!NOTE] ツールは読み取りと更新操作に制限されており、削除操作は公開されていません。これにより、意図しないアクションの影響範囲を小さく抑えます。セキュリティに関する考慮事項を参照してください。

仕組み

サーバーは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セキュリティ設定のキーに置き換えてください。

[!TIP] アカウントがMailgunのEUリージョンでホストされている場合は、"MAILGUN_API_REGION": "eu" を env ブロック（または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"
}

[!TIP] バイナリを --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"!

[!NOTE] 一部の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: alice@example.com, bob@example.com.

ドメインを比較する

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.

受信トレイ配置を確認する (最適化)

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

メールをプレビューする (検査)

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仕様をコピーします。MCPクライアントを npx ではなくビルドされたエントリポイントに向けます（絶対パスを使用してください）:

{
  "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. npm run build を一度実行して dist/openapi.yaml を配置します。

2. 保存のたびに dist/ を再ビルドするためにTypeScriptコンパイラを実行し続けます:

   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 はgitプレコミットフックを（husky経由で）インストールし、ステージングされたTypeScript/JavaScriptファイルに対して oxlint --fix と oxfmt を実行し、npm run check:versions を実行します。修正可能な問題は自動修正されて再ステージングされ、修正不可能なlintエラーやバージョン同期の不一致を引き起こすコミットは拒否されます。この変更前にローカルクローンが既にあった場合は、npm install を一度実行してフックをインストールしてください。

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

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

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

APIキーの分離

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

ローカル実行

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

APIキーの権限

必要な操作のみにスコープされた権限を持つ専用のMailgun APIキーを使用してください。サーバーは読み取りおよび更新操作を公開しますが、削除操作は公開しないため、意図しないアクションの影響範囲を制限します。

レート制限

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

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

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

Webhook URL

Webhookの作成および更新操作は、AIアシスタントを通じて提供された任意のURLを受け入れます。MCPサーバーはこれらのURLを追加の検証なしにMailgun APIに渡します。MailgunはWebhook宛先の検証を担当します。AIアシスタントがWebhook URLを意図しない内部アドレスや機密アドレスに設定しないようにしてください。

入力検証

すべてのツールパラメータは、Zodスキーマを使用してMailgun OpenAPI仕様に対して検証されます。ただし、検証はOpenAPI仕様の正確さに依存し、一部のエッジケースパラメータは許容的な検証にフォールバックする可能性があります。Mailgun APIは、追加の保護層として独自のサーバー側検証を実行します。

デバッグ

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

ライセンス

Apache 2.0 — 詳細は LICENSE を参照してください。

貢献

貢献を歓迎します！お気軽に Pull Request を送信するか、Issue を作成してください。