Mailgun MCP Server

chính thức

Tương tác với API Mailgun.

GitHub
56

Tài liệu

Máy chủ Mailgun MCP

MCP

Tổng quan

Máy chủ Model Context Protocol (MCP) dành cho Mailgun cung cấp cho các tác nhân AI một giao diện thực tế, hướng quy trình để gửi email, chẩn đoán khả năng gửi đến và quản lý các thao tác tài khoản.

Lưu ý: Máy chủ MCP này chạy cục bộ trên máy của bạn. Mailgun hiện không cung cấp phiên bản lưu trữ của máy chủ này.

Khả năng

  • Nhắn tin — Gửi email, truy xuất tin nhắn đã lưu, gửi lại tin nhắn
  • Tên miền — Xem chi tiết tên miền, xác minh cấu hình DNS, quản lý cài đặt theo dõi (nhấp, mở, hủy đăng ký)
  • Webhook — Liệt kê, tạo, cập nhật và xóa webhook sự kiện
  • Tuyến đường — Xem và cập nhật quy tắc định tuyến email đến
  • Danh sách gửi thư — Tạo và quản lý danh sách gửi thư cùng thành viên
  • Mẫu — Tạo và quản lý mẫu email với phiên bản hóa
  • Phân tích — Truy vấn chỉ số gửi, chỉ số sử dụng và nhật ký
  • Thống kê — Xem thống kê tổng hợp theo tên miền, thẻ, nhà cung cấp, thiết bị và quốc gia
  • Chặn — Xem thư bị trả lại, hủy đăng ký, khiếu nại và mục danh sách cho phép
  • IP & Nhóm IP — Xem phân bổ IP và cấu hình nhóm IP chuyên dụng
  • Phân loại thư trả lại — Phân tích loại thư trả lại và vấn đề gửi đến

Điều kiện tiên quyết

  • Node.js (v20.12 trở lên)
  • Tài khoản Mailgun và khóa API

Bắt đầu nhanh

Cấu hình

Thêm nội dung sau vào cấu hình máy khách MCP của bạn:

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

Biến môi trường

BiếnBắt buộcMặc địnhMô tả
MAILGUN_API_KEYCó—Khóa API Mailgun của bạn
MAILGUN_API_REGIONKhôngusVùng API: us hoặc eu
MAILGUN_MCP_TAGSKhông(tất cả)Thẻ sản phẩm phân cách bằng dấu phẩy để kích hoạt. Tương đương với --tags. Cờ CLI được ưu tiên.

Lọc thẻ

Bạn có thể giới hạn phạm vi công cụ mà máy chủ đăng ký vào một hoặc nhiều thẻ sản phẩm Mailgun. Điều này hữu ích để thu hẹp bộ công cụ hiển thị cho mô hình — ví dụ: chỉ hiển thị công cụ xác thực cho quy trình không cần khả năng gửi.

Thẻ hợp lệ: send, validate, optimize, inspect. Khi không chỉ định, mọi công cụ đều được đăng ký (mặc định hiện tại).

Lọc sử dụng ngữ nghĩa HOẶC: một công cụ được đăng ký nếu bất kỳ thẻ nào của nó xuất hiện trong tập đang hoạt động.

Qua cờ CLI — truyền --tags trong args của cấu hình máy khách MCP:

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

Qua biến môi trường — đặt MAILGUN_MCP_TAGS (cờ CLI thắng nếu cả hai cùng có):

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

Khả năng khám phá — chạy tệp nhị phân với --list-tags để in giá trị thẻ được hỗ trợ, hoặc --help để xem hướng dẫn đầy đủ. Thẻ không xác định bị từ chối khi khởi động với thông báo lỗi rõ ràng.

Đường dẫn cấu hình cụ thể cho máy khách

  • Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
  • Claude Desktop (Windows): %APPDATA%/Claude/claude_desktop_config.json
  • Claude Code: Chạy claude mcp add hoặc chỉnh sửa ~/.claude.json

Lời nhắc mẫu

Gửi 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"!

Lưu ý: một số máy khách MCP yêu cầu gói trả phí để gọi công cụ gửi dữ liệu. Nếu gửi thất bại âm thầm, hãy kiểm tra gói của máy khách.

Lấy và Trực quan hóa Thống kê Gửi

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

Quản lý Mẫu

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

Điều tra Khả năng Gửi đến

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

Khắc phục sự cố DNS

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

Xem xét Chặn

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

Quản lý Quy tắc Định tuyến

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

Tạo Danh sách Gửi thư

Create a mailing list called announcements@DOMAIN_HERE and add these
members: [email protected], [email protected].

So sánh Tên miền

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

Tương tác theo Khu vực

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

Xem lại Cài đặt Theo dõi

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

Phát triển

Để chạy từ mã nguồn, sao chép kho lưu trữ và sử dụng trực tiếp node:

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

Trong cấu hình máy khách MCP của bạn, thay thế lệnh npx bằng:

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

Hook tiền cam kết

npm install cài đặt hook tiền cam kết git (qua husky) chạy oxlint --fix và oxfmt trên các tệp TypeScript/JavaScript đã staged và chạy npm run check:versions. Các vấn đề có thể sửa được tự động sửa và staged lại; các cam kết gây ra lỗi lint không sửa được hoặc không khớp đồng bộ phiên bản bị từ chối. Nếu bạn đã có bản sao cục bộ trước thay đổi này, chạy npm install một lần để cài đặt hook.

Lưu ý khi thêm điểm cuối

Khi thêm điểm cuối mới, nếu bạn sử dụng chuỗi thuần cho định nghĩa của nó, nó sẽ mặc định được gắn thẻ loại sản phẩm send trong trường _meta. Nếu bạn muốn gắn thẻ nó là sản phẩm khác, hãy sử dụng phiên bản đối tượng của kiểu EndpointEntry.

Cân nhắc Bảo mật

Cô lập khóa API

Khóa API Mailgun của bạn được truyền dưới dạng biến môi trường và không bao giờ bị lộ cho chính mô hình AI — nó chỉ được sử dụng bởi tiến trình máy chủ MCP để xác thực yêu cầu. Máy chủ không ghi nhật ký khóa API, tham số yêu cầu hoặc dữ liệu phản hồi.

Thực thi cục bộ

Máy chủ chạy cục bộ trên máy của bạn. Mọi giao tiếp với API Mailgun đều qua HTTPS với xác thực chứng chỉ TLS được thực thi. Không có dữ liệu nào được gửi đến dịch vụ bên thứ ba ngoài API Mailgun.

Quyền khóa API

Sử dụng khóa API Mailgun chuyên dụng với quyền được giới hạn chỉ cho các thao tác bạn cần. Máy chủ hiển thị thao tác đọc và cập nhật nhưng không hiển thị bất kỳ thao tác xóa nào, điều này giới hạn phạm vi ảnh hưởng của các hành động không mong muốn.

Giới hạn tốc độ

Máy chủ không triển khai giới hạn tốc độ phía máy khách. Mỗi lần gọi công cụ từ AI chuyển trực tiếp thành một yêu cầu API Mailgun. Máy chủ dựa vào giới hạn tốc độ phía máy chủ của Mailgun để ngăn chặn lạm dụng — các yêu cầu vượt quá giới hạn đó sẽ trả về lỗi cho trợ lý AI.

Tiêm lời nhắc

Như với bất kỳ máy chủ MCP nào, một lời nhắc được tạo ra hoặc đối nghịch có thể lừa trợ lý AI gọi các thao tác bạn không dự định — ví dụ: sửa đổi cài đặt theo dõi hoặc đọc thành viên danh sách gửi thư. Xem lại xác nhận gọi công cụ của trợ lý AI trước khi phê duyệt hành động, đặc biệt trong ngữ cảnh lời nhắc không đáng tin cậy.

URL Webhook

Thao tác tạo và cập nhật webhook chấp nhận URL tùy ý được cung cấp qua trợ lý AI. Máy chủ MCP chuyển các URL này đến API Mailgun mà không xác thực thêm. Mailgun chịu trách nhiệm xác thực đích webhook. Đảm bảo trợ lý AI của bạn không đặt URL webhook đến địa chỉ nội bộ hoặc nhạy cảm không mong muốn.

Xác thực đầu vào

Tất cả tham số công cụ được xác thực dựa trên đặc tả OpenAPI của Mailgun bằng lược đồ Zod. Tuy nhiên, việc xác thực phụ thuộc vào độ chính xác của đặc tả OpenAPI và một số tham số biên có thể rơi vào xác thực dễ dãi. API Mailgun thực hiện xác thực phía máy chủ riêng như một lớp bảo vệ bổ sung.

Gỡ lỗi

Máy chủ MCP giao tiếp qua stdio. Tham khảo Hướng dẫn Gỡ lỗi MCP để khắc phục sự cố.

Giấy phép

Apache 2.0 — xem LICENSE để biết chi tiết.

Đóng góp

Chúng tôi hoan nghênh đóng góp! Vui lòng gửi Pull Request hoặc mở Issue.