Mailgun

Mailgun MCP Sunucusu

Genel Bakış

Mailgun için Model Context Protocol (MCP) sunucusu; yapay zekâ aracılarına e-posta gönderme, teslim edilebilirlik sorunlarını teşhis etme ve hesap işlemlerini yönetme için pratik, iş akışı odaklı bir arayüz sunar.

[!NOTE] Bu MCP sunucusu makinenizde yerel olarak çalışır ve stdio üzerinden iletişim kurar. Mailgun şu anda bu sunucunun barındırılan bir sürümünü sunmamaktadır.

Özellikler

• Mesajlaşma — E-posta gönderme, depolanan mesajları alma ve mesajları yeniden gönderme
• Alan adları — Alan adı ayrıntılarını görüntüleme, DNS yapılandırmasını doğrulama, izleme ayarlarını yönetme (tıklama, açılma, abonelikten çıkma)
• Webhook'lar — Olay webhook'larını listeleme, oluşturma ve güncelleme
• Rotalar — Gelen e-posta yönlendirme kurallarını görüntüleme ve güncelleme
• Posta listeleri — Posta listelerini ve üyelerini oluşturma, görüntüleme ve güncelleme
• Şablonlar — Sürüm oluşturma özelliğiyle e-posta şablonlarını oluşturma, görüntüleme ve güncelleme
• Analitik — Gönderim metriklerini, kullanım metriklerini ve günlükleri sorgulama
• İstatistikler — Alan adına, etikete, sağlayıcıya, cihaza ve ülkeye göre toplu istatistikleri görüntüleme
• Bastırmalar — Geri dönmeleri, abonelikten çıkmaları, şikâyetleri ve izin listesi kayıtlarını görüntüleme
• IP'ler ve IP havuzları — IP atamalarını ve özel IP havuzu yapılandırmasını görüntüleme
• Geri dönme sınıflandırması — Geri dönme türlerini ve teslimat sorunlarını analiz etme
• Doğrulama — Göndermeden önce e-posta adresinin teslim edilebilirliğini ve sözdizimini doğrulama (validate)
• Optimize (Gelen kutusuna yerleşim) — Teslim edilebilirliği değerlendirmek için gelen kutusuna yerleşim / tohum testi sonuçlarını alma (optimize)
• Inspect (E-posta önizlemesi) — İstemciler genelinde e-posta oluşturma ve önizleme testi sonuçlarını alma (inspect)
• Hesap sınırları — Özel aylık gönderim sınırlarını görüntüleme

Yukarıdaki etiketler (validate, optimize, inspect), etiket filtrelemede kullanılan ürün etiketleridir. Diğer tüm özellikler send etiketi altında kaydedilir ve bu etiket send.<group> araç kümelerine ayrılır.

[!NOTE] Araçlar okuma ve güncelleme işlemleriyle sınırlıdır — silme işlemleri sunulmaz; böylece istenmeyen bir eylemin etki alanı küçük tutulur. Güvenlik Hususları bölümüne bakın.

Nasıl çalışır?

Sunucu OpenAPI odaklıdır. Başlangıçta paketlenmiş bir Mailgun OpenAPI belirtimini ayrıştırır ve uç noktaların seçilmiş bir izin listesini MCP araçları olarak kaydeder; her aracın girdi şemasını belirtimden (Zod aracılığıyla) oluşturur. Her araçta bir Mailgun ürün etiketi (send, validate, optimize veya inspect), ait olduğu araç kümesi ve yalnızca veri okuyup okumadığı belirtilir.

Varsayılan olarak sunucu başlangıçta tüm araçları yükler. --tags dynamic kullanıldığında, küçük bir temel araç kümesini ve modelin gerektiğinde daha fazla araç kümesi yüklemek için kullandığı üç aracı yükler; böylece modele gönderilen araç tanımları küçük tutulur. Etiket filtreleme bunun yerine başlangıçta sabit bir araç kümesi yükler; böylece belirli bir iş akışı yalnızca ihtiyaç duyduğu ürünleri sunabilir.

Ön Koşullar

• Node.js (v20.12 veya üzeri)
• Mailgun hesabı ve API anahtarı

Kurulum

Sunucu npm'de @mailgun/mcp-server olarak yayımlanır ve stdio üzerinden çalışır. Çoğu istemci sunucuyu npx ile gerektiğinde başlatabilir; bu nedenle genel olarak kurulum yapmanız gerekmez. Aşağıdaki her kod örneğinde YOUR-mailgun-api-key yerine Mailgun API güvenlik ayarlarınızdan aldığınız bir anahtarı yazın.

[!TIP] Hesabınız Mailgun'un AB bölgesinde barındırılıyorsa, "MAILGUN_API_REGION": "eu" değerini env bloğuna (veya CLI'da -e MAILGUN_API_REGION=eu değerini) ekleyin. Varsayılan değer us şeklindedir.

Claude Code

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

Ardından mailgun sunucusunun bağlı olduğunu doğrulamak için Claude Code'da /mcp komutunu çalıştırın.

Claude Desktop

Settings → Developer → Edit Config bölümünü açın veya dosyayı doğrudan düzenleyin:

• 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

Komut paletini açın ve Cursor Settings → MCP → Add new global MCP server seçeneğini belirleyin, ardından şunu ekleyin:

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

Aşağıdakini settings.json dosyanıza ekleyin:

{
  "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 dosyasına ekleyin:

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

Yapılandırma

Ortam değişkenleri

Değişken	Gerekli	Varsayılan	Açıklama
MAILGUN_API_KEY	Evet	—	Mailgun API anahtarınız
MAILGUN_API_REGION	Hayır	us	API bölgesi: us veya eu
MAILGUN_API_HOSTNAME	Hayır	(bölgeden türetilir)	API ana bilgisayar adını geçersiz kılar (ör. api.eu.mailgun.net). Bölge ayarına göre önceliklidir.
MAILGUN_MCP_TAGS	Hayır	(tümü)	Yüklenecek, virgülle ayrılmış etiketler veya araç kümeleri ya da isteğe bağlı olarak daha fazlasının yüklendiği temel araçlar için dynamic. --tags ile eşdeğerdir. CLI bayrağı önceliklidir.

CLI seçenekleri

Bayrakları istemcinizin args alanında paket adından sonra geçirin (ör. ["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"]).

Bayrak	Açıklama
--tags <list>	Yüklenecek, virgülle ayrılmış etiketler veya araç kümeleri (varsayılan: tümü). Geçerli değerler: all, dynamic, core, send, validate, optimize, inspect ve send.<group> araç kümeleri.
--list-tags	Açıklamalarıyla birlikte tüm geçerli --tags değerlerini yazdırıp çık.
--help, -h	Kullanım bilgisini gösterip çık.

İsteğe bağlı araç kümeleri

--tags dynamic (veya MAILGUN_MCP_TAGS=dynamic) kullanıldığında sunucu şu temel araçlarla başlar:

Araç	Amaç
post-v3-domain-messages	E-posta gönderme
get-v4-domains	Alan adlarını listeleme
get-v4-domains-name	Alan adı ayrıntıları ve DNS kayıtları
put-v4-domains-name-verify	Alan adının DNS kayıtlarını yeniden denetleme
get-v3-domains-name-tracking	İzleme ayarları
get_metrics_summary	Temel gönderim metriklerinin özeti
post-v1-analytics-metrics	Hesap metriklerini sorgulama
post-v1-analytics-logs	Olay günlüklerini sorgulama
post-v2-bounce-classification-metrics	Geri dönme sınıflandırma metrikleri
get-v3-domain-bounces	Geri dönmeleri listeleme
get-v3-domain-bounces-address	Geri dönme kaydını arama
get-v3-domain-unsubscribes	Abonelikten çıkmaları listeleme
get-v3-domain-complaints	Şikâyetleri listeleme
get-v3-domain-templates	Şablonları listeleme
validate_email	E-posta adresini doğrulama

Her araç bir araç kümesine aittir. Bir görev gerektirdiğinde model, araç kümesinin geri kalanını yükler:

Araç kümesi	Araçlar	İçerik
send.messages	3	E-posta gönderme; depolanan mesajları alma ve yeniden gönderme
send.domains	8	Alan adları, DNS doğrulaması, gönderim kuyrukları, izleme ayarları
send.webhooks	4	Alan adı webhook'ları
send.account	8	Hesap IP'leri, özel IP havuzları, özel gönderim sınırları
send.message_tags	8	Mesaj etiketleri, etikete göre istatistikler, etiket sınırları
send.analytics	12	İstatistikler ve toplamlar, analitik metrikleri ve günlükleri, geri dönme sınıflandırması
send.suppressions	8	Geri dönmeler, abonelikten çıkmalar, şikâyetler, izin listesi
send.routes	3	Gelen rotalar
send.lists	8	Posta listeleri ve üyeler
send.templates	8	Şablonlar ve şablon sürümleri
validate	1	E-posta adresi doğrulaması
optimize	1	Gelen kutusuna yerleşim testi sonuçları
inspect	1	E-posta önizleme testi sonuçları

Model, araç kümelerini üç ek araçla yükler:

• mailgun_list_toolsets, tüm araç kümelerini ve araçlarını listeler; hangilerinin yüklü olduğunu ve hangilerinin verileri değiştirdiğini belirtir. Bir araç adı verildiğinde bunun yerine o aracın girdi şemasını döndürür.
• mailgun_enable_toolset, bir veya daha fazla araç kümesini yükler. Ardından sunucu, istemciye araç listesinin değiştiğini bildirir (notifications/tools/list_changed) ve yeni araçlar temel araçların yanında görünür. Yanıt, yeni araçları girdi şemaları olmadan listeler; şemalar güncellenmiş araç listesiyle birlikte gelir.
• mailgun_call_tool, araç kümesi yüklü olsun ya da olmasın, salt okunur bir aracı adına göre çalıştırır. Bu, değişiklikten sonra araç listesini yenilemeyen istemciler için bir yedek yöntemdir. Temel araçları ve verileri değiştiren araçları reddeder; bu araçlar her zaman kendi araç çağrıları olarak çalıştırılır.

Yüklenen araç kümeleri, istemci bağlantıyı kesene kadar kullanılabilir. İsteğe bağlı yükleme, sunucu değişiklik bildirdiğinde araç listesini yenileyen bir istemci gerektirir; Claude Code bunu yapar. Bunu yapmayan istemcilerde yeni yüklenen araçlar görünmez: salt okunur araçlar yine de mailgun_call_tool üzerinden çalışır; verileri değiştiren araçlar içinse varsayılan ayar (tüm araçlar) veya örneğin --tags olan --tags core,send.templates gerekir.

Etiket filtreleme

--tags veya MAILGUN_MCP_TAGS değerini dynamic dışında bir değere ayarlamak, yükleme araçları olmadan yalnızca eşleşen araçları başlangıçta yükler. Bunu modele gösterilen araçları daraltmak için kullanın (örneğin, e-posta göndermeyen bir iş akışı için yalnızca doğrulama araçları).

Geçerli değerler (açıklamalar için --list-tags komutunu çalıştırın):

• all — tüm araçlar (varsayılan)
• dynamic — diğer araç kümelerinin isteğe bağlı olarak yüklendiği temel araçlar. Bunu tek başına kullanın; başka değerlerle birleştirmek başlangıçta hataya neden olur.
• core — yalnızca yukarıda listelenen temel araçlar
• send, validate, optimize, inspect — ilgili ürünün tüm araçları (send, tüm send.<group> araç kümelerini kapsar)
• send.templates gibi bir araç kümesi kimliği

Filtreleme VEYA mantığı kullanır: listedeki herhangi bir değerle eşleşen araç yüklenir. Örneğin, core,send.templates temel araçları ve tüm şablon araçlarını yükler.

CLI bayrağıyla — MCP istemci yapılandırmanızın args alanında --tags değerini geçirin:

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

Ortam değişkeniyle — MAILGUN_MCP_TAGS değerini ayarlayın (ikisi de mevcutsa CLI bayrağı önceliklidir):

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

[!TIP] Tüm geçerli değerleri yazdırmak için ikili dosyayı --list-tags ile, tam kullanım bilgisini görmek için --help ile çalıştırın. Bilinmeyen değerler, açık bir hata mesajıyla başlangıçta reddedilir.

Örnek İstemler

E-posta Gönderme

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] Bazı MCP istemcileri, veri gönderen araçları çağırmak için ücretli plan gerektirir. Gönderim sessizce başarısız olursa istemcinizin planını kontrol edin.

Gönderim İstatistiklerini Getirme ve Görselleştirme

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

Şablonları Yönetme

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

Teslim Edilebilirliği İnceleme

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

DNS Sorunlarını Giderme

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

Bastırma Listelerini İnceleme

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

Yönlendirme Kurallarını Yönetme

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

Bir Posta Listesi Oluşturma

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

Alan Adlarını Karşılaştırma

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

Bölgeye Göre Etkileşim

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

İzleme Ayarlarını İnceleme

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

Bir E-posta Adresini Doğrulama

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

Gelen Kutusuna Yerleşimi Kontrol Etme (Optimize)

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

Bir E-postayı Önizleme (Inspect)

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

Geliştirme

Kaynak koddan çalıştırma

Sunucu TypeScript ile yazılmıştır. Depoyu klonlayın, bağımlılıkları yükleyin, derleyin ve test edin:

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/ öğesini dist/ konumuna derler ve paketlenmiş OpenAPI belirtimini kopyalar. MCP istemcinizi npx yerine derlenmiş giriş dosyasını kullanacak şekilde ayarlayın (mutlak bir yol kullanın):

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

Düzenleme sırasında canlı test

MCP sunucuları uzun süre çalışan stdio süreçleridir ve otomatik olarak yeniden yüklenmez. Bu nedenle iş akışı şöyledir: her kaydetme işleminde yeniden derleyin, ardından değişiklikleri almak için istemciyi yeniden bağlayın.

1. npm run build komutunu bir kez çalıştırarak dist/openapi.yaml öğesinin hazır olmasını sağlayın.

2. Her kaydetme işleminde dist/ öğesini yeniden derlemek için TypeScript derleyicisini çalışır durumda tutun:

   npx tsc --watch
   

3. Ayrı bir MCP istemcisini (veya aşağıdaki MCP Inspector'ı) dist/mailgun-mcp.js konumuna yönlendirin. Değişiklik yaptıktan sonra yeni derlemeyi yüklemek için MCP istemci oturumunu yeniden başlatın.

MCP Inspector ile test etme

MCP Inspector, araçları tam özellikli bir istemci olmadan denemenizi sağlar. Önce derleyin, ardından derlenmiş sunucuyla başlatın:

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

Inspector kullanıcı arayüzünü açın, Connect düğmesine tıklayın ve sunucunun çalıştığını doğrulamak için List Tools seçeneğini kullanın. Filtrelenmiş bir araç kümesini test etmek için sunucu yolundan sonra bayrakları ekleyin:

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

Commit öncesi kancalar

npm install, oxlint --fix ve oxfmt komutlarını hazırlama alanındaki TypeScript/JavaScript dosyalarında çalıştıran ve npm run check:versions komutunu çalıştıran bir git commit öncesi kancasını (husky aracılığıyla) yükler. Düzeltilebilir sorunlar otomatik olarak düzeltilip yeniden hazırlama alanına eklenir; düzeltilemeyen lint hatalarına veya sürüm eşitleme uyuşmazlıklarına yol açan commit'ler reddedilir. Bu değişiklikten önce yerel bir klonunuz varsa kancayı yüklemek için npm install komutunu bir kez çalıştırın.

Uç nokta ekleme hakkında not

Uç noktalar, endpointGroups içinde araç kümelerine göre gruplandırılır. Düz bir dize girdisi, ürün etiketini araç kümesinden alır (send.templates → send) ve yalnızca bir GET ise salt okunur olarak değerlendirilir. Araç adını ayarlamak, bir aracı core olarak işaretlemek (dinamik modda başlangıçta yüklenir) veya yalnızca veri sorgulayan bir POST öğesini readOnly: true olarak işaretlemek için EndpointEntry nesne biçimini kullanın.

Güvenlikle İlgili Hususlar

API anahtarı yalıtımı

Mailgun API anahtarınız bir ortam değişkeni olarak aktarılır ve yapay zekâ modelinin kendisine hiçbir zaman gösterilmez; yalnızca MCP sunucusu süreci tarafından isteklerin kimliğini doğrulamak için kullanılır. Sunucu API anahtarlarını, istek parametrelerini veya yanıt verilerini günlüğe kaydetmez.

Yerel yürütme

Sunucu makinenizde yerel olarak çalışır. Mailgun API ile tüm iletişim, TLS sertifika doğrulaması zorunlu tutularak HTTPS üzerinden gerçekleştirilir. Mailgun API dışında üçüncü taraf hizmetlere veri gönderilmez.

API anahtarı izinleri

Yalnızca ihtiyacınız olan işlemlerle sınırlı izinlere sahip, özel bir Mailgun API anahtarı kullanın. Sunucu okuma ve güncelleme işlemlerini sunar ancak silme işlemlerini sunmaz; bu da istenmeyen eylemlerin olası etkisini sınırlar.

Hız sınırlama

Sunucu, istemci tarafında hız sınırlaması uygulamaz. Yapay zekâdan gelen her araç çağrısı doğrudan bir Mailgun API isteğine dönüşür. Sunucu, kötüye kullanımı önlemek için Mailgun'ın sunucu tarafı hız sınırlarına güvenir; bu sınırları aşan istekler yapay zekâ asistanına hata döndürür.

İstem enjeksiyonu

Her MCP sunucusunda olduğu gibi, hazırlanmış veya kötü amaçlı bir istem yapay zekâ asistanını istemediğiniz işlemleri çağırmaya yönlendirebilir; örneğin izleme ayarlarını değiştirebilir veya posta listesi üyelerini okuyabilir. Özellikle güvenilmeyen istem bağlamlarında, eylemleri onaylamadan önce yapay zekâ asistanınızın araç çağrısı onaylarını inceleyin.

Araç yükleme ve onaylar

Her araç, MCP readOnlyHint açıklamasını taşır; böylece istemciler yalnızca veri okuyan araçları verileri değiştiren araçlardan ayırt edebilir (örneğin onay isterken). mailgun_list_toolsets ve mailgun_call_tool salt okunurdur. mailgun_enable_toolset, oturumun gördüğü araçları değiştirir; bu nedenle salt okunur olarak işaretlenmez, ancak Mailgun'da hiçbir şeyi değiştirmez. mailgun_call_tool, yalnızca temel kümede bulunmayan salt okunur araçları çalıştırır; dolayısıyla onaylanması hiçbir zaman e-posta gönderemez veya hesap ayarlarını değiştiremez. Verileri değiştiren araçlar her zaman kendi araç çağrıları olarak çalışır.

Araç kümelerini isteğe bağlı olarak yüklemek, modelin gördüğü içeriği azaltır; ancak bu bir erişim denetimi değildir, çünkü model herhangi bir araç kümesini yükleyebilir. Sunucunun hangi araçları kullanıma sunduğunu sınırlamak için --tags kullanın.

Webhook URL'leri

Webhook oluşturma ve güncelleme işlemleri, yapay zekâ asistanı aracılığıyla sağlanan rastgele URL'leri kabul eder. MCP sunucusu bu URL'leri ek doğrulama yapmadan Mailgun API'ye iletir. Webhook hedeflerini doğrulamak Mailgun'ın sorumluluğundadır. Yapay zekâ asistanınızın webhook URL'lerini istenmeyen dahili veya hassas adreslere ayarlamadığından emin olun.

Girdi doğrulama

Tüm araç parametreleri, Zod şemaları kullanılarak Mailgun OpenAPI belirtimine göre doğrulanır. Ancak doğrulama, OpenAPI belirtiminin doğruluğuna bağlıdır ve bazı uç durum parametreleri izin verici doğrulamaya geri dönebilir. Mailgun API, ek bir koruma katmanı olarak kendi sunucu tarafı doğrulamasını gerçekleştirir.

Hata ayıklama

MCP sunucusu stdio üzerinden iletişim kurar. Sorun giderme için MCP Hata Ayıklama Kılavuzu'na bakın.

Lisans

Apache 2.0 — ayrıntılar için LICENSE dosyasına bakın.

Katkıda Bulunma

Katkılarınızı memnuniyetle karşılıyoruz! Lütfen bir Pull Request göndermekten veya bir Issue açmaktan çekinmeyin.