Mailgun

Mailgun MCP Server

Ringkasan

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

[!NOTE] Server MCP ini berjalan secara lokal di mesin Anda dan berkomunikasi melalui stdio. Saat ini Mailgun belum menyediakan versi server ini yang di-host.

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 — Mencantumkan, membuat, dan memperbarui webhook peristiwa
• Rute — Melihat dan memperbarui aturan perutean email masuk
• Milis — Membuat, melihat, dan memperbarui milis beserta anggotanya
• Templat — Membuat, melihat, dan memperbarui templat email dengan pembuatan versi
• Analitik — Mengkueri metrik pengiriman, metrik penggunaan, dan log
• Statistik — Melihat statistik agregat berdasarkan domain, tag, penyedia, perangkat, dan negara
• Penekanan — Melihat pantulan, berhenti berlangganan, keluhan, dan entri daftar izin
• IP & Kumpulan IP — Melihat penetapan IP dan konfigurasi kumpulan IP khusus
• Klasifikasi Pantulan — Menganalisis jenis pantulan dan masalah pengiriman
• Validasi — Memvalidasi keterkiriman dan sintaks alamat email sebelum mengirim (validate)
• Optimize (Penempatan Kotak Masuk) — Mengambil hasil pengujian penempatan kotak masuk / seed untuk mengukur keterkiriman (optimize)
• Inspect (Pratinjau Email) — Mengambil hasil pengujian rendering dan pratinjau email di berbagai klien (inspect)
• Batas Akun — Melihat batas pengiriman bulanan khusus

Label di atas (validate, optimize, inspect) adalah tag produk yang digunakan oleh pemfilteran tag. Semua kemampuan lainnya didaftarkan di bawah tag send, yang dibagi menjadi send.<group> toolset.

[!NOTE] Tool hanya menyediakan operasi baca dan pembaruan — tidak ada operasi penghapusan, sehingga dampak dari tindakan yang tidak disengaja tetap kecil. Lihat Pertimbangan Keamanan.

Cara kerjanya

Server ini digerakkan oleh OpenAPI. Saat startup, server mengurai spesifikasi OpenAPI Mailgun yang disertakan dan mendaftarkan daftar izin endpoint terpilih sebagai tool MCP, dengan membuat skema input setiap tool (melalui Zod) dari spesifikasi tersebut. Setiap tool diberi anotasi tag produk Mailgun (send, validate, optimize, atau inspect), toolset tempatnya berada, dan apakah tool tersebut hanya membaca data.

Secara default, server memuat semua tool saat startup. Dengan --tags dynamic, server memuat kumpulan inti tool berukuran kecil beserta tiga tool yang digunakan model untuk memuat lebih banyak toolset sesuai kebutuhan, sehingga definisi tool yang dikirim ke model tetap ringkas. Pemfilteran tag memuat kumpulan tool tetap saat startup, sehingga alur kerja tertentu dapat menampilkan hanya produk yang dibutuhkan.

Prasyarat

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

Instalasi

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

[!TIP] Jika akun Anda di-host 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

Lalu jalankan /mcp di Claude Code untuk memastikan 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 berikut ini ke 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

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	Wajib	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)	Ganti nama host API (misalnya api.eu.mailgun.net). Diutamakan daripada wilayah.
MAILGUN_MCP_TAGS	Tidak	(semua)	Tag atau toolset yang akan dimuat, dipisahkan koma, atau dynamic untuk tool inti dengan tool lain yang dimuat sesuai kebutuhan. Setara dengan --tags. Opsi CLI lebih diutamakan.

Opsi CLI

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

Flag	Deskripsi
--tags <list>	Tag atau toolset yang akan dimuat, dipisahkan koma (default: semua). Nilai yang valid: all, dynamic, core, send, validate, optimize, inspect, dan toolset send.<group>.
--list-tags	Cetak setiap nilai --tags yang valid beserta deskripsinya, lalu keluar.
--help, -h	Tampilkan penggunaan dan keluar.

Toolset sesuai kebutuhan

Dengan --tags dynamic (atau MAILGUN_MCP_TAGS=dynamic), server dimulai dengan tool inti berikut:

Tool	Tujuan
post-v3-domain-messages	Mengirim email
get-v4-domains	Mencantumkan domain
get-v4-domains-name	Detail domain dan catatan DNS
put-v4-domains-name-verify	Memeriksa ulang catatan DNS domain
get-v3-domains-name-tracking	Pengaturan pelacakan
get_metrics_summary	Ringkasan metrik pengiriman utama
post-v1-analytics-metrics	Mengkueri metrik akun
post-v1-analytics-logs	Mengkueri log peristiwa
post-v2-bounce-classification-metrics	Metrik klasifikasi pantulan
get-v3-domain-bounces	Mencantumkan pantulan
get-v3-domain-bounces-address	Mencari catatan pantulan
get-v3-domain-unsubscribes	Mencantumkan berhenti berlangganan
get-v3-domain-complaints	Mencantumkan keluhan
get-v3-domain-templates	Mencantumkan templat
validate_email	Memvalidasi alamat email

Setiap tool termasuk dalam sebuah toolset. Model memuat toolset lainnya saat tugas membutuhkannya:

Toolset	Tool	Isi
send.messages	3	Mengirim email; mengambil dan mengirim ulang pesan tersimpan
send.domains	8	Domain, verifikasi DNS, antrean pengiriman, pengaturan pelacakan
send.webhooks	4	Webhook domain
send.account	8	IP akun, kumpulan IP khusus, batas pengiriman khusus
send.message_tags	8	Tag pesan, statistik berdasarkan tag, batas tag
send.analytics	12	Statistik dan agregat, metrik dan log analitik, klasifikasi pantulan
send.suppressions	8	Pantulan, berhenti berlangganan, keluhan, daftar izin
send.routes	3	Rute masuk
send.lists	8	Milis dan anggota
send.templates	8	Templat dan versi templat
validate	1	Validasi alamat email
optimize	1	Hasil pengujian penempatan kotak masuk
inspect	1	Hasil pengujian pratinjau email

Model memuat toolset dengan tiga tool tambahan:

• mailgun_list_toolsets mencantumkan semua toolset dan tool di dalamnya, serta menandai mana yang sudah dimuat dan mana yang mengubah data. Jika diberi nama tool, tool ini akan mengembalikan skema input tool tersebut.
• mailgun_enable_toolset memuat satu atau beberapa toolset. Server kemudian memberi tahu klien bahwa daftar tool-nya berubah (notifications/tools/list_changed), dan tool baru muncul bersama tool inti. Respons mencantumkan tool baru tanpa skema inputnya; skema tersebut disertakan dalam daftar tool yang diperbarui.
• mailgun_call_tool menjalankan tool hanya-baca berdasarkan nama, baik toolset-nya sudah dimuat maupun belum. Ini merupakan solusi cadangan untuk klien yang tidak memperbarui daftar tool setelah terjadi perubahan. Tool ini menolak tool inti dan tool yang mengubah data, sehingga tool tersebut selalu dijalankan sebagai pemanggilan tool tersendiri.

Toolset yang dimuat tetap tersedia hingga klien terputus. Pemuatan sesuai kebutuhan memerlukan klien yang memperbarui daftar tool saat server melaporkan perubahan; Claude Code mendukungnya. Pada klien yang tidak mendukungnya, tool yang baru dimuat tidak akan muncul: tool hanya-baca tetap dapat digunakan melalui mailgun_call_tool, sedangkan tool yang mengubah data memerlukan konfigurasi default (semua tool) atau --tags, misalnya --tags core,send.templates.

Pemfilteran tag

Mengatur --tags atau MAILGUN_MCP_TAGS ke nilai selain dynamic akan memuat tepat tool yang cocok saat startup, tanpa tool pemuatan. Gunakan opsi ini untuk membatasi tool yang ditampilkan kepada model (misalnya, hanya tool validasi untuk alur kerja yang tidak mengirim email).

Nilai yang valid (jalankan --list-tags untuk melihat deskripsinya):

• all — semua tool (default)
• dynamic — tool inti, dengan toolset lain dimuat sesuai kebutuhan. Gunakan sendiri; menggabungkannya dengan nilai lain akan menyebabkan startup gagal.
• core — hanya tool inti yang tercantum di atas
• send, validate, optimize, inspect — semua tool untuk produk tersebut (send mencakup semua toolset send.<group>)
• ID toolset seperti send.templates

Pemfilteran menggunakan semantik OR: tool dimuat jika cocok dengan nilai apa pun dalam daftar. Misalnya, core,send.templates memuat tool inti beserta semua tool templat.

Melalui flag CLI — teruskan --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 (flag CLI lebih diutamakan jika keduanya ditetapkan):

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

[!TIP] Jalankan biner dengan --list-tags untuk mencetak semua nilai yang valid, atau --help untuk melihat panduan penggunaan lengkap. Nilai yang tidak dikenal akan ditolak saat startup dengan pesan kesalahan yang jelas.

Contoh Prompt

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 menjalankan alat yang mengirim data. Jika pengiriman gagal tanpa pesan, periksa paket klien Anda.

Mengambil dan Memvisualisasikan Statistik Pengiriman

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

Mengelola Templat

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

Menyelidiki Keterkiriman

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

Memecahkan Masalah DNS

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

Meninjau Penekanan

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

Mengelola Aturan Perutean

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

Membuat Milis

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

Membandingkan Domain

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

Interaksi Berdasarkan Wilayah

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

Meninjau Pengaturan Pelacakan

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

Memvalidasi Alamat Email

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

Memeriksa Penempatan di Kotak Masuk (Optimize)

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

Mempratinjau Email (Inspect)

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

Pengembangan

Menjalankan dari kode sumber

Server ini ditulis dalam TypeScript. Klon, 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/ menjadi dist/ dan menyalin spesifikasi OpenAPI yang dibundel. Arahkan klien MCP Anda ke entry yang telah dibangun, bukan ke 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 mengedit

Server MCP adalah proses stdio berumur panjang yang tidak dimuat ulang secara otomatis, jadi alurnya adalah: bangun ulang setiap kali disimpan, lalu sambungkan kembali klien untuk menerapkan perubahan.

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

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

   npx tsc --watch
   

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

Menguji dengan MCP Inspector

MCP Inspector memungkinkan Anda menguji alat tanpa klien lengkap. Bangun terlebih dahulu, lalu jalankan dengan server yang telah dibangun:

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

Buka UI Inspector, klik Connect, lalu gunakan List Tools untuk memastikan server berfungsi. Untuk menguji kumpulan alat yang difilter, tambahkan flag setelah jalur server:

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

Hook pra-commit

npm install memasang hook git pra-commit (melalui husky) yang menjalankan oxlint --fix dan oxfmt pada file TypeScript/JavaScript yang telah di-stage, serta menjalankan npm run check:versions. Masalah yang dapat diperbaiki akan diperbaiki secara otomatis dan di-stage ulang; commit 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 memasang hook.

Catatan tentang penambahan endpoint

Endpoint dikelompokkan berdasarkan kumpulan alat di endpointGroups. Entri string biasa mengambil tag produknya dari kumpulan alatnya (send.templates → send) dan dianggap hanya-baca hanya jika berupa GET. Gunakan bentuk objek EndpointEntry untuk menetapkan nama alat, menandai alat sebagai core (dimuat saat startup dalam mode dinamis), atau menandai POST yang hanya mengkueri data sebagai readOnly: true.

Pertimbangan Keamanan

Isolasi kunci API

Kunci API Mailgun Anda diteruskan sebagai variabel lingkungan dan tidak pernah diekspos ke model AI itu sendiri — kunci tersebut 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 dilakukan melalui HTTPS dengan validasi sertifikat TLS yang diberlakukan. Tidak ada data yang dikirim ke layanan pihak ketiga selain API Mailgun.

Izin kunci API

Gunakan kunci API Mailgun khusus dengan izin yang dibatasi hanya pada operasi yang Anda perlukan. Server menyediakan operasi baca dan pembaruan, tetapi tidak menyediakan operasi penghapusan apa pun, sehingga membatasi dampak tindakan yang tidak disengaja.

Pembatasan laju

Server tidak menerapkan pembatasan laju di sisi klien. Setiap pemanggilan alat oleh AI langsung diterjemahkan menjadi permintaan API Mailgun. Server mengandalkan batas laju sisi server Mailgun untuk mencegah penyalahgunaan — permintaan yang melampaui batas tersebut akan mengembalikan kesalahan kepada asisten AI.

Injeksi prompt

Seperti server MCP lainnya, prompt yang dirancang dengan cermat atau bersifat adversarial dapat mengelabui asisten AI agar memanggil operasi yang tidak Anda maksudkan — misalnya, mengubah pengaturan pelacakan atau membaca anggota milis. Tinjau konfirmasi pemanggilan alat dari asisten AI Anda sebelum menyetujui tindakan, terutama dalam konteks prompt yang tidak tepercaya.

Pemuatan dan persetujuan alat

Setiap alat memiliki anotasi MCP readOnlyHint, sehingga klien dapat membedakan alat yang hanya membaca data dari alat yang mengubahnya (misalnya, saat meminta persetujuan). mailgun_list_toolsets dan mailgun_call_tool hanya-baca. mailgun_enable_toolset mengubah alat yang terlihat oleh sesi, sehingga tidak ditandai sebagai hanya-baca, tetapi tidak pernah mengubah apa pun di Mailgun. mailgun_call_tool hanya menjalankan alat hanya-baca yang tidak termasuk dalam kumpulan inti, sehingga menyetujuinya tidak akan pernah mengirim email atau mengubah pengaturan akun. Alat yang mengubah data selalu dijalankan sebagai pemanggilan alat tersendiri.

Memuat kumpulan alat sesuai kebutuhan mengurangi hal yang dilihat model; ini bukan kontrol akses, karena model dapat memuat kumpulan alat apa pun. Untuk membatasi alat yang disediakan server, gunakan --tags.

URL webhook

Operasi pembuatan dan pembaruan webhook menerima URL sembarang yang diberikan melalui asisten AI. Server MCP meneruskan URL ini ke API Mailgun tanpa validasi tambahan. Mailgun bertanggung jawab memvalidasi tujuan webhook. Pastikan asisten AI Anda tidak menetapkan URL webhook ke alamat internal atau sensitif yang tidak dimaksudkan.

Validasi input

Semua parameter alat divalidasi terhadap spesifikasi OpenAPI Mailgun menggunakan skema Zod. Namun, validasi bergantung pada keakuratan spesifikasi OpenAPI, dan beberapa parameter kasus khusus mungkin menggunakan validasi yang 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.

Kontribusi

Kami menyambut kontribusi! Silakan kirim Pull Request atau buat Issue.