Skip to content

Mailgun MCP tool for ADK

Supported in ADKPythonTypeScriptGo

The Mailgun MCP Server connects your ADK agent to Mailgun, a transactional email service. This integration gives your agent the ability to send emails, track delivery metrics, manage domains and templates, and handle mailing lists using natural language.

Use cases

  • Send and Manage Emails: Compose and send transactional or marketing emails, retrieve stored messages, and resend messages through conversational commands.

  • Monitor Delivery Performance: Fetch delivery statistics, analyze bounce classifications, and review suppression lists to maintain sender reputation.

  • Manage Email Infrastructure: Verify domain DNS configuration, configure tracking settings, create email templates, and set up inbound routing rules.

Prerequisites

Use with agent

from google.adk.agents import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
from mcp import StdioServerParameters

MAILGUN_API_KEY = "YOUR_MAILGUN_API_KEY"

root_agent = Agent(
    model="gemini-flash-latest",
    name="mailgun_agent",
    instruction="Help users send emails and manage their Mailgun account",
    tools=[
        McpToolset(
            connection_params=StdioConnectionParams(
                server_params=StdioServerParameters(
                    command="npx",
                    args=[
                        "-y",
                        "@mailgun/mcp-server",
                    ],
                    env={
                        "MAILGUN_API_KEY": MAILGUN_API_KEY,
                        # "MAILGUN_API_REGION": "eu",  # Optional: defaults to "us"
                    }
                ),
                timeout=30,
            ),
        )
    ],
)

import { LlmAgent, MCPToolset } from "@google/adk";

const MAILGUN_API_KEY = "YOUR_MAILGUN_API_KEY";

const rootAgent = new LlmAgent({
    model: "gemini-flash-latest",
    name: "mailgun_agent",
    instruction: "Help users send emails and manage their Mailgun account",
    tools: [
        new MCPToolset({
            type: "StdioConnectionParams",
            serverParams: {
                command: "npx",
                args: ["-y", "@mailgun/mcp-server"],
                env: {
                    MAILGUN_API_KEY: MAILGUN_API_KEY,
                    // MAILGUN_API_REGION: "eu",  // Optional: defaults to "us"
                },
            },
        }),
    ],
});

export { rootAgent };

package main

import (
    "context"
    "log"
    "os"
    "os/exec"

    "github.com/modelcontextprotocol/go-sdk/mcp"
    "google.golang.org/genai"

    "google.golang.org/adk/v2/agent"
    "google.golang.org/adk/v2/agent/llmagent"
    "google.golang.org/adk/v2/cmd/launcher"
    "google.golang.org/adk/v2/cmd/launcher/full"
    "google.golang.org/adk/v2/model/gemini"
    "google.golang.org/adk/v2/tool"
    "google.golang.org/adk/v2/tool/mcptoolset"
)

const mailgunAPIKey = "YOUR_MAILGUN_API_KEY"

func main() {
    ctx := context.Background()

    model, err := gemini.NewModel(ctx, "gemini-flash-latest", &genai.ClientConfig{
        APIKey: os.Getenv("GOOGLE_API_KEY"),
    })
    if err != nil {
        log.Fatalf("Failed to create the model: %v", err)
    }

    server := exec.CommandContext(ctx, "npx", "-y", "@mailgun/mcp-server")
    // Forward only what npx needs, plus the Mailgun key. The parent environment
    // may hold unrelated secrets, such as the GOOGLE_API_KEY read above.
    server.Env = []string{
        "MAILGUN_API_KEY=" + mailgunAPIKey,
        // "MAILGUN_API_REGION=eu", // Optional: defaults to "us"
    }
    for _, k := range []string{
        "PATH", "HOME", // POSIX
        "APPDATA", "LOCALAPPDATA", "TEMP", "USERPROFILE", // Windows
    } {
        if v, ok := os.LookupEnv(k); ok {
            server.Env = append(server.Env, k+"="+v)
        }
    }

    mailgun, err := mcptoolset.New(mcptoolset.Config{
        Transport: &mcp.CommandTransport{Command: server},
    })
    if err != nil {
        log.Fatalf("Failed to create the Mailgun tool set: %v", err)
    }

    rootAgent, err := llmagent.New(llmagent.Config{
        Model:       model,
        Name:        "mailgun_agent",
        Instruction: "Help users send emails and manage their Mailgun account",
        Toolsets:    []tool.Toolset{mailgun},
    })
    if err != nil {
        log.Fatalf("Failed to create the agent: %v", err)
    }

    l := full.NewLauncher()
    cfg := &launcher.Config{AgentLoader: agent.NewSingleLoader(rootAgent)}
    if err := l.Execute(ctx, cfg, os.Args[1:]); err != nil {
        log.Fatalf("Run failed: %v\n\n%s", err, l.CommandLineSyntax())
    }
}

Available tools

Messaging

Tool Description
send_email Send an email with support for HTML content and attachments
get_stored_message Retrieve a stored email message
resend_message Resend a previously sent message

Domains

Tool Description
get_domain View details for a specific domain
verify_domain Verify DNS configuration for a domain
get_tracking_settings View tracking settings (click, open, unsubscribe)
update_tracking_settings Update tracking settings for a domain

Webhooks

Tool Description
list_webhooks List all event webhooks for a domain
create_webhook Create a new event webhook
update_webhook Update an existing webhook
delete_webhook Delete a webhook

Routes

Tool Description
list_routes View inbound email routing rules
update_route Update an inbound routing rule

Mailing lists

Tool Description
create_mailing_list Create a new mailing list
manage_list_members Add, remove, or update mailing list members

Templates

Tool Description
create_template Create a new email template
manage_template_versions Create and manage template versions

Analytics and stats

Tool Description
query_metrics Query sending and usage metrics for a date range
get_logs Retrieve email event logs
get_stats View aggregate statistics by domain, tag, provider, device, or country

Suppressions

Tool Description
get_bounces View bounced email addresses
get_unsubscribes View unsubscribed email addresses
get_complaints View complaint records
get_allowlist View allowlist entries

IPs

Tool Description
list_ips View IP assignments
get_ip_pools View dedicated IP pool configuration

Bounce classification

Tool Description
get_bounce_classification Analyze bounce types and delivery issues

Configuration

Variable Required Default Description
MAILGUN_API_KEY Yes — Your Mailgun API key
MAILGUN_API_REGION No us API region: us or eu

Additional resources