Mailgun

Server MCP Mailgun

Gambaran Umum

Server Model Context Protocol (MCP) untuk Mailgun yang memberikan agen AI antarmuka praktis dan berorientasi alur kerja untuk mengirim email, mendiagnosis keterkiriman, dan mengelola operasi akun.

[!NOTE] Server MCP ini berjalan secara lokal di mesin Anda dan berkomunikasi melalui stdio. Mailgun saat ini tidak menawarkan versi terhosting dari server ini.

Kemampuan

• Pesan — Mengirim email, mengambil pesan tersimpan, mengirim ulang pesan
• Domain — Melihat detail domain, memverifikasi konfigurasi DNS, mengelola pengaturan pelacakan (klik, buka, berhenti berlangganan)
• Webhook — Mendaftar, membuat, dan memperbarui webhook acara
• Rute — Melihat dan memperbarui aturan perutean email masuk
• Milis — Membuat, melihat, dan memperbarui milis serta anggotanya
• Templat — Membuat, melihat, dan memperbarui templat email dengan pembuatan versi
• Analitik — Menanyakan metrik pengiriman, metrik penggunaan, dan log
• Statistik — Melihat statistik agregat berdasarkan domain, tag, penyedia, perangkat, dan negara
• Penekanan — Melihat pentalan, berhenti berlangganan, keluhan, dan entri daftar izin
• IP & Kumpulan IP — Melihat penetapan IP dan konfigurasi kumpulan IP khusus
• Klasifikasi Pentalan — Menganalisis jenis pentalan dan masalah pengiriman
• Validasi — Memvalidasi keterkiriman dan sintaks alamat email sebelum mengirim (validate)
• Optimalkan (Penempatan Kotak Masuk) — Mengambil hasil penempatan kotak masuk / uji benih untuk mengukur keterkiriman (optimize)
• Periksa (Pratinjau Email) — Mengambil hasil rendering email dan uji pratinjau di berbagai klien (inspect)
• Batas Akun — Melihat batas pengiriman bulanan khusus

Label dalam kurung di atas (validate, optimize, inspect) adalah tag produk yang digunakan oleh pemfilteran tag. Setiap kemampuan lainnya terdaftar di bawah tag send.

[!NOTE] Alat dibatasi pada operasi baca dan perbarui — tidak ada operasi hapus yang diekspos, yang menjaga radius ledakan dari tindakan yang tidak diinginkan tetap kecil. Lihat Pertimbangan Keamanan.

Cara kerjanya

Server ini digerakkan oleh OpenAPI. Saat startup, server mengurai spesifikasi OpenAPI Mailgun yang dibundel dan mendaftarkan daftar izin titik akhir yang dikurasi sebagai alat MCP, menghasilkan skema input setiap alat (melalui Zod) dari spesifikasi tersebut. Setiap alat dianotasi dengan tag produk Mailgun (send, validate, optimize, atau inspect). Semua alat yang cocok didaftarkan di awal — tidak ada pemuatan malas atau sesuai permintaan. Pemfilteran tag diterapkan saat startup untuk membatasi alat mana yang didaftarkan, sehingga alur kerja tertentu hanya dapat mengekspos produk yang dibutuhkannya.

Prasyarat

• Node.js (v20.12 atau lebih tinggi)
• Akun Mailgun dan kunci API

Instalasi

Server dipublikasikan ke npm sebagai @mailgun/mcp-server dan berjalan melalui stdio. Sebagian besar klien dapat meluncurkannya sesuai permintaan dengan npx, jadi tidak ada yang perlu diinstal secara global. Di setiap cuplikan di bawah, ganti YOUR-mailgun-api-key dengan kunci dari pengaturan keamanan API Mailgun Anda.

[!TIP] Jika akun Anda dihosting di wilayah EU Mailgun, tambahkan "MAILGUN_API_REGION": "eu" ke blok env (atau -e MAILGUN_API_REGION=eu di CLI). Nilai defaultnya adalah us.

Claude Code

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

Kemudian jalankan /mcp di Claude Code untuk mengonfirmasi bahwa server mailgun terhubung.

Claude Desktop

Buka Settings → Developer → Edit Config, atau edit file secara langsung:

• 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

Buka palet perintah dan pilih Cursor Settings → MCP → Add new global MCP server, lalu tambahkan:

{
  "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)

Tambahkan yang berikut ke settings.json Anda:

{
  "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

Tambahkan ke ~/.gemini/settings.json:

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

Konfigurasi

Variabel lingkungan

Variabel	Diperlukan	Default	Deskripsi
MAILGUN_API_KEY	Ya	—	Kunci API Mailgun Anda
MAILGUN_API_REGION	Tidak	us	Wilayah API: us atau eu
MAILGUN_API_HOSTNAME	Tidak	(diturunkan dari wilayah)	Timpa nama host API (mis. api.eu.mailgun.net). Diutamakan daripada wilayah.
MAILGUN_MCP_TAGS	Tidak	(semua)	Tag produk yang dipisahkan koma untuk diaktifkan. Setara dengan --tags. Bendera CLI diutamakan.

Opsi CLI

Berikan bendera setelah nama paket di args klien Anda (mis. ["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"]).

Bendera	Deskripsi
--tags <list>	Tag produk yang dipisahkan koma untuk diaktifkan (default: semua). Valid: send, validate, optimize, inspect.
--list-tags	Cetak nilai tag yang valid dan keluar.
--help, -h	Tampilkan penggunaan dan keluar.

Pemfilteran tag

Anda dapat membatasi alat mana yang didaftarkan server ke satu atau beberapa tag produk Mailgun. Ini berguna untuk mempersempit kumpulan alat yang ditampilkan ke model — misalnya, hanya mengekspos alat validasi ke alur kerja yang tidak memerlukan kemampuan mengirim.

Tag yang valid: send, validate, optimize, inspect. Jika tidak ditentukan, setiap alat didaftarkan (default saat ini).

Pemfilteran menggunakan semantik OR: sebuah alat didaftarkan jika salah satu tagnya muncul di set aktif.

Melalui bendera CLI — berikan --tags di args konfigurasi klien MCP Anda:

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

Melalui variabel lingkungan — atur MAILGUN_MCP_TAGS (bendera CLI menang jika keduanya ada):

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

[!TIP] Jalankan biner dengan --list-tags untuk mencetak nilai tag yang didukung, atau --help untuk penggunaan lengkap. Tag yang tidak dikenal ditolak saat startup dengan pesan kesalahan yang jelas.

Contoh Perintah

Kirim Email

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] Beberapa klien MCP memerlukan paket berbayar untuk memanggil alat yang mengirim data. Jika pengiriman gagal secara diam-diam, periksa paket klien Anda.

Ambil dan Visualisasikan Statistik Pengiriman

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

Kelola Templat

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

Selidiki Keterkiriman

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

Pecahkan Masalah DNS

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

Tinjau Penekanan

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

Kelola Aturan Perutean

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

Buat Milis

Create a mailing list called announcements@DOMAIN_HERE and add these
members: alice@example.com, bob@example.com.

Bandingkan Domain

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

Keterlibatan berdasarkan Wilayah

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

Tinjau Pengaturan Pelacakan

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

Validasi Alamat Email

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

Periksa Penempatan Kotak Masuk (Optimalkan)

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

Pratinjau Email (Periksa)

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

Pengembangan

Jalankan dari sumber

Server ditulis dalam TypeScript. Kloning, instal, bangun, dan uji:

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

npm run build mengompilasi src/ ke dist/ dan menyalin spesifikasi OpenAPI yang dibundel. Arahkan klien MCP Anda ke entri yang dibangun alih-alih npx (gunakan jalur absolut):

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

Pengujian langsung saat Anda mengedit

Server MCP adalah proses stdio yang berjalan lama dan tidak memuat ulang secara otomatis, jadi siklusnya adalah: bangun ulang saat menyimpan, lalu sambungkan kembali klien untuk mengambil perubahan.

1. Jalankan npm run build sekali agar dist/openapi.yaml tersedia.

2. Biarkan kompiler TypeScript berjalan untuk membangun ulang dist/ setiap kali menyimpan:

   npx tsc --watch
   

3. Arahkan klien MCP terpisah (atau Inspektur MCP, di bawah) ke dist/mailgun-mcp.js. Setelah perubahan, mulai ulang sesi klien MCP untuk memuat build baru.

Pengujian dengan Inspektur MCP

Inspektur MCP memungkinkan Anda menggunakan alat tanpa klien penuh. Bangun terlebih dahulu, lalu luncurkan terhadap server yang dibangun:

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

Buka UI Inspektur, klik Connect, lalu gunakan List Tools untuk memverifikasi server berfungsi. Untuk menguji kumpulan alat yang difilter, tambahkan bendera setelah jalur server:

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

Hook pra-komit

npm install menginstal hook git pra-komit (melalui husky) yang menjalankan oxlint --fix dan oxfmt pada file TypeScript/JavaScript yang staged dan menjalankan npm run check:versions. Masalah yang dapat diperbaiki akan otomatis diperbaiki dan di-staging ulang; komit yang menimbulkan kesalahan lint yang tidak dapat diperbaiki atau ketidakcocokan sinkronisasi versi akan ditolak. Jika Anda sudah memiliki klon lokal sebelum perubahan ini, jalankan npm install sekali untuk menginstal hook.

Catatan tentang menambahkan titik akhir

Saat menambahkan titik akhir baru, jika Anda menggunakan string biasa untuk definisinya, secara default akan ditandai dengan tipe produk send di bidang _meta. Jika Anda ingin menandainya sebagai produk yang berbeda, gunakan versi objek dari tipe EndpointEntry.

Pertimbangan Keamanan

Isolasi kunci API

Kunci API Mailgun Anda diteruskan sebagai variabel lingkungan dan tidak pernah diekspos ke model AI itu sendiri — kunci ini hanya digunakan oleh proses server MCP untuk mengautentikasi permintaan. Server tidak mencatat kunci API, parameter permintaan, atau data respons.

Eksekusi lokal

Server berjalan secara lokal di mesin Anda. Semua komunikasi dengan API Mailgun melalui HTTPS dengan validasi sertifikat TLS yang diterapkan. Tidak ada data yang dikirim ke layanan pihak ketiga di luar API Mailgun.

Izin kunci API

Gunakan kunci API Mailgun khusus dengan izin yang dibatasi hanya pada operasi yang Anda butuhkan. Server mengekspos operasi baca dan perbarui tetapi tidak mengekspos operasi hapus apa pun, yang membatasi radius ledakan dari tindakan yang tidak diinginkan.

Pembatasan laju

Server tidak menerapkan pembatasan laju sisi klien. Setiap panggilan alat dari AI diterjemahkan langsung menjadi permintaan API Mailgun. Server mengandalkan batas laju sisi server Mailgun untuk mencegah penyalahgunaan — permintaan yang melebihi batas tersebut akan mengembalikan kesalahan ke asisten AI.

Injeksi perintah

Seperti halnya server MCP lainnya, perintah yang dibuat atau adversarial dapat menipu asisten AI untuk memanggil operasi yang tidak Anda inginkan — misalnya, mengubah pengaturan pelacakan atau membaca anggota milis. Tinjau konfirmasi panggilan alat asisten AI Anda sebelum menyetujui tindakan, terutama dalam konteks perintah yang tidak tepercaya.

URL Webhook

Operasi buat dan perbarui webhook menerima URL arbitrer yang disediakan melalui asisten AI. Server MCP meneruskan URL ini ke API Mailgun tanpa validasi tambahan. Mailgun bertanggung jawab untuk memvalidasi tujuan webhook. Pastikan asisten AI Anda tidak menetapkan URL webhook ke alamat internal atau sensitif yang tidak diinginkan.

Validasi input

Semua parameter alat divalidasi terhadap spesifikasi OpenAPI Mailgun menggunakan skema Zod. Namun, validasi bergantung pada keakuratan spesifikasi OpenAPI, dan beberapa parameter kasus tepi mungkin kembali ke validasi permisif. API Mailgun melakukan validasi sisi servernya sendiri sebagai lapisan perlindungan tambahan.

Debugging

Server MCP berkomunikasi melalui stdio. Lihat Panduan Debugging MCP untuk pemecahan masalah.

Lisensi

Apache 2.0 — lihat LICENSE untuk detailnya.

Berkontribusi

Kami menyambut kontribusi! Silakan kirimkan Pull Request atau buka Issue.