Mailgun

Mailgun MCP Sunucusu

Genel Bakış

Mailgun için, yapay zeka ajanlarına e-posta gönderme, teslim edilebilirliği teşhis etme ve hesap işlemlerini yönetme için pratik, iş akışı odaklı bir arayüz sağlayan bir Model Bağlam Protokolü (MCP) sunucusu.

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

Yetenekler

• Mesajlaşma — E-postalar gönderin, saklanan mesajları alın, mesajları yeniden gönderin
• Alan Adları — Alan adı ayrıntılarını görüntüleyin, DNS yapılandırmasını doğrulayın, izleme ayarlarını yönetin (tıklama, açma, abonelikten çıkma)
• Web Kancaları — Olay web kancalarını listeleyin, oluşturun ve güncelleyin
• Rotalar — Gelen e-posta yönlendirme kurallarını görüntüleyin ve güncelleyin
• Posta Listeleri — Posta listelerini ve üyelerini oluşturun, görüntüleyin ve güncelleyin
• Şablonlar — Sürümleme ile e-posta şablonları oluşturun, görüntüleyin ve güncelleyin
• Analitik — Gönderim metriklerini, kullanım metriklerini ve günlükleri sorgulayın
• İstatistikler — Alan adı, etiket, sağlayıcı, cihaz ve ülkeye göre toplu istatistikleri görüntüleyin
• Engellemeler — Geri dönen e-postaları, abonelikten çıkmaları, şikayetleri ve izin listesi girişlerini görüntüleyin
• IP'ler ve IP Havuzları — IP atamalarını ve özel IP havuzu yapılandırmasını görüntüleyin
• Geri Dönme Sınıflandırması — Geri dönme türlerini ve teslimat sorunlarını analiz edin
• Doğrulama — Göndermeden önce e-posta adresi teslim edilebilirliğini ve sözdizimini doğrulayın (validate)
• Optimize Et (Gelen Kutusu Yerleşimi) — Teslim edilebilirliği ölçmek için gelen kutusu yerleşimi / tohum testi sonuçlarını alın (optimize)
• İncele (E-posta Önizleme) — İstemciler arasında e-posta işleme ve önizleme testi sonuçlarını alın (inspect)
• Hesap Limitleri — Özel aylık gönderim limitlerini görüntüleyin

Yukarıdaki parantez içindeki etiketler (validate, optimize, inspect), etiket filtreleme tarafından kullanılan ürün etiketleridir. Diğer tüm yetenekler send etiketi altında kayıtlıdır.

[!NOTE] Araçlar okuma ve güncelleme işlemleriyle sınırlıdır — silme işlemleri sunulmaz, bu da istenmeyen bir eylemin etki alanını küçük tutar. Bkz. Güvenlik Hususları.

Nasıl çalışır

Sunucu OpenAPI odaklıdır. Başlangıçta paketlenmiş bir Mailgun OpenAPI şartnamesini ayrıştırır ve şartnameden her aracın girdi şemasını (Zod aracılığıyla) oluşturarak, seçilmiş bir uç nokta izin listesini MCP araçları olarak kaydeder. Her araç bir Mailgun ürün etiketiyle (send, validate, optimize veya inspect) açıklanmıştır. Tüm eşleşen araçlar önceden kaydedilir — tembel veya isteğe bağlı yükleme yoktur. Etiket filtreleme, hangi araçların kaydedileceğini kapsamak için başlangıçta uygulanır, böylece belirli bir iş akışı yalnızca ihtiyaç duyduğu ürünleri sunabilir.

Ön Koşullar

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

Kurulum

Sunucu npm'de @mailgun/mcp-server olarak yayınlanır ve stdio üzerinden çalışır. Çoğu istemci bunu npx ile isteğe bağlı olarak başlatabilir, bu nedenle global olarak kurulacak bir şey yoktur. Aşağıdaki her kod parçasında, YOUR-mailgun-api-key ifadesini Mailgun API güvenlik ayarlarınızdan bir anahtarla değiştirin.

[!TIP] Hesabınız Mailgun'un AB bölgesinde barındırılıyorsa, env bloğuna (veya CLI'da -e MAILGUN_API_REGION=eu) "MAILGUN_API_REGION": "eu" ekleyin. Varsayılan olarak 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

Ayarlar → Geliştirici → Yapılandırmayı Düzenle'yi 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 Ayarları → MCP → Yeni global MCP sunucusu ekle'yi seçin, 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ıl (örn. api.eu.mailgun.net). Bölgeye göre önceliklidir.
MAILGUN_MCP_TAGS	Hayır	(tümü)	Etkinleştirilecek virgülle ayrılmış ürün etiketleri. --tags ile eşdeğerdir. CLI bayrağı önceliklidir.

CLI seçenekleri

İstemcinizin args bölümünde paket adından sonra bayrakları iletin (örn. ["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"]).

Bayrak	Açıklama
--tags <list>	Etkinleştirilecek virgülle ayrılmış ürün etiketleri (varsayılan: tümü). Geçerli: send, validate, optimize, inspect.
--list-tags	Geçerli etiket değerlerini yazdır ve çık.
--help, -h	Kullanımı göster ve çık.

Etiket filtreleme

Sunucunun hangi araçları kaydedeceğini bir veya daha fazla Mailgun ürün etiketiyle kapsamlandırabilirsiniz. Bu, modele gösterilen araç setini daraltmak için kullanışlıdır — örneğin, gönderme yeteneklerine ihtiyaç duymayan bir iş akışına yalnızca doğrulama araçlarını sunmak.

Geçerli etiketler: send, validate, optimize, inspect. Belirtilmediğinde, her araç kaydedilir (bugünkü varsayılan).

Filtreleme VEYA mantığı kullanır: bir araç, etkin kümede etiketlerinden herhangi biri görünüyorsa kaydedilir.

CLI bayrağı ile — MCP istemci yapılandırmanızın args bölümünde --tags iletin:

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

Ortam değişkeni ile — MAILGUN_MCP_TAGS ayarlayın (her ikisi de mevcutsa CLI bayrağı kazanır):

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

[!TIP] Desteklenen etiket değerlerini yazdırmak için ikili dosyayı --list-tags ile veya tam kullanım için --help ile çalıştırın. Bilinmeyen etiketler başlangıçta net bir hata mesajıyla reddedilir.

Örnek İstemler

Bir E-posta Gönder

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 bir plan gerektirir. Gönderme sessizce başarısız olursa, istemcinizin planını kontrol edin.

Gönderim İstatistiklerini Al ve Görselleştir

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

Şablonları Yönet

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 Araştır

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

DNS Sorunlarını Gider

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

Engellemeleri İncele

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

Yönlendirme Kurallarını Yönet

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

Bir Posta Listesi Oluştur

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

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

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ı İncele

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

Bir E-posta Adresini Doğrula

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

Gelen Kutusu Yerleşimini Kontrol Et (Optimize Et)

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ı Önizle (İncele)

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

Geliştirme

Kaynaktan çalıştırma

Sunucu TypeScript ile yazılmıştır. Klonlayın, kurun, 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/'i dist/'e derler ve paketlenmiş OpenAPI şartnamesini kopyalar. MCP istemcinizi npx yerine derlenmiş girişe yönlendirin (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ı, anında yeniden yükleme yapmayan uzun ömürlü stdio süreçleridir, bu nedenle döngü şöyledir: kaydetmede yeniden derle, ardından değişiklikleri almak için istemciyi yeniden bağla.

1. dist/openapi.yaml'ün yerinde olduğundan emin olmak için npm run build'yi bir kez çalıştırın.

2. Her kaydetmede dist/'ü 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'e yönlendirin. Bir değişiklikten sonra, yeni derlemeyi yüklemek için MCP istemci oturumunu yeniden başlatın.

MCP Inspector ile Test Etme

MCP Inspector, tam bir istemci olmadan araçları kullanmanıza olanak tanır. Önce derleyin, ardından derlenmiş sunucuya karşı 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, Bağlan'a tıklayın, ardından sunucunun çalıştığını doğrulamak için Araçları Listele'yi kullanın. Filtrelenmiş bir araç setini 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

Ön işleme kancaları

npm install, hazırlanmış TypeScript/JavaScript dosyalarında oxlint --fix ve oxfmt'i çalıştıran ve npm run check:versions'i çalıştıran bir git ön işleme kancası (husky aracılığıyla) yükler. Düzeltilebilir sorunlar otomatik olarak düzeltilir ve yeniden hazırlanır; düzeltilemez lint hataları veya sürüm senkronizasyonu uyumsuzlukları getiren işlemeler reddedilir. Bu değişiklikten önce zaten yerel bir klonunuz varsa, kancayı yüklemek için npm install'i bir kez çalıştırın.

Uç noktalar ekleme hakkında not

Yeni bir uç nokta eklerken, tanımı için düz bir dize kullanırsanız, _meta alanında varsayılan olarak send ürün türüyle etiketlenir. Farklı bir ürün olarak etiketlemek isterseniz, EndpointEntry türünün nesne sürümünü kullanın.

Güvenlik Hususları

API anahtarı izolasyonu

Mailgun API anahtarınız bir ortam değişkeni olarak iletilir ve asla yapay zeka modelinin kendisine sunulmaz — yalnızca MCP sunucu süreci tarafından istekleri 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 yerel olarak makinenizde çalışır. Mailgun API ile tüm iletişim, TLS sertifika doğrulaması zorunlu olarak HTTPS üzerinden yapılır. Mailgun API dışında üçüncü taraf hizmetlere hiçbir veri gönderilmez.

API anahtarı izinleri

Yalnızca ihtiyacınız olan işlemlere kapsamlandırılmış izinlere sahip özel bir Mailgun API anahtarı kullanın. Sunucu, okuma ve güncelleme işlemlerini sunar ancak herhangi bir silme işlemi sunmaz, bu da istenmeyen eylemlerin etki alanını sınırlar.

Hız sınırlaması

Sunucu, istemci tarafı hız sınırlaması uygulamaz. Yapay zekadan 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'un sunucu tarafı hız limitlerine güvenir — bu limitleri aşan istekler yapay zeka asistanına bir hata döndürür.

İstem enjeksiyonu

Herhangi bir MCP sunucusunda olduğu gibi, hazırlanmış veya düşmanca bir istem, yapay zeka asistanını, örneğin izleme ayarlarını değiştirmek veya posta listesi üyelerini okumak gibi, sizin amaçlamadığınız işlemleri çağırması için kandırabilir. Özellikle güvenilmeyen istem bağlamlarında, eylemleri onaylamadan önce yapay zeka asistanınızın araç çağrısı onaylarını inceleyin.

Web kancası URL'leri

Web kancası oluşturma ve güncelleme işlemleri, yapay zeka asistanı aracılığıyla sağlanan rastgele URL'leri kabul eder. MCP sunucusu, bu URL'leri ek doğrulama olmaksızın Mailgun API'ye iletir. Web kancası hedeflerini doğrulamaktan Mailgun sorumludur. Yapay zeka asistanınızın, web kancası URL'lerini istenmeyen dahili veya hassas adreslere ayarlamadığından emin olun.

Girdi doğrulaması

Tüm araç parametreleri, Zod şemaları kullanılarak Mailgun OpenAPI şartnamesine göre doğrulanır. Ancak doğrulama, OpenAPI şartnamesinin 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 Çekme İsteği göndermekten veya bir Sorun açmaktan çekinmeyin.