Mailgun MCP Server

resmi

Berinteraksi dengan API Mailgun.

GitHub
56

Dokumentasi

Server MCP Mailgun

MCP

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.

Catatan: Server MCP ini berjalan secara lokal di mesin Anda. 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, memperbarui, dan menghapus webhook peristiwa
  • Rute — Melihat dan memperbarui aturan perutean email masuk
  • Milis — Membuat dan mengelola milis serta anggotanya
  • Templat — Membuat dan mengelola templat email dengan pembuatan versi
  • Analitik — Kueri 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

Prasyarat

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

Mulai Cepat

Konfigurasi

Tambahkan yang berikut ke konfigurasi klien MCP Anda:

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

Variabel Lingkungan

VariabelDiperlukanDefaultDeskripsi
MAILGUN_API_KEYYa—Kunci API Mailgun Anda
MAILGUN_API_REGIONTidakusWilayah API: us atau eu
MAILGUN_MCP_TAGSTidak(semua)Tag produk yang dipisahkan koma untuk diaktifkan. Setara dengan --tags. Bendera CLI lebih diutamakan.

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 akan didaftarkan (default saat ini).

Pemfilteran menggunakan semantik ATAU: 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"
}

Kemudahan ditemukan — 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.

Jalur Konfigurasi Spesifik Klien

  • Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
  • Claude Desktop (Windows): %APPDATA%/Claude/claude_desktop_config.json
  • Claude Code: Jalankan claude mcp add atau edit ~/.claude.json

Contoh Perintah

Mengirim 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"!

Catatan: beberapa klien MCP memerlukan paket berbayar untuk menjalankan alat yang mengirim data. Jika pengiriman gagal tanpa pemberitahuan, 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: [email protected], [email protected].

Membandingkan 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.

Meninjau Pengaturan Pelacakan

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

Pengembangan

Untuk menjalankan dari sumber, kloning repositori dan gunakan node secara langsung:

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

Di konfigurasi klien MCP Anda, ganti perintah npx dengan:

"command": "node",
"args": ["/path/to/mailgun-mcp-server/src/mailgun-mcp.js"]

Hook pra-komit

npm install memasang hook git pra-komit (melalui husky) yang menjalankan oxlint --fix dan oxfmt pada file TypeScript/JavaScript yang di-staging 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 memasang 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 ditegakkan. 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 untuk operasi yang Anda butuhkan. Server mengekspos operasi baca dan perbarui tetapi tidak mengekspos operasi penghapusan 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 langsung diterjemahkan 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 bersifat adversarial dapat mengelabui 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 pembuatan dan pembaruan 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 masukan

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.