Mailgun

Mailgun MCP Server

Tổng quan

Một 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 làm việc để 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.

[!NOTE] Máy chủ MCP này chạy cục bộ trên máy của bạn và giao tiếp qua stdio. 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ý)
• Webhooks — Liệt kê, tạo và cập nhật webhooks sự kiện
• Lộ trình — Xem và cập nhật quy tắc định tuyến email đến
• Danh sách gửi thư — Tạo, xem và cập nhật danh sách gửi thư và thành viên của chúng
• Mẫu — Tạo, xem và cập nhật mẫu email với phiên bản hóa
• Phân tích — Truy vấn số liệu gửi, số liệu 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 các thư bị trả lại, hủy đăng ký, khiếu nại và các mục trong 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 các loại thư trả lại và vấn đề gửi đến
• Xác thực — Xác thực khả năng gửi đến và cú pháp địa chỉ email trước khi gửi (validate)
• Tối ưu hóa (Vị trí hộp thư đến) — Truy xuất kết quả kiểm tra vị trí hộp thư đến / kiểm tra hạt giống để đánh giá khả năng gửi đến (optimize)
• Kiểm tra (Xem trước email) — Truy xuất kết quả kiểm tra hiển thị và xem trước email trên các ứng dụng khách (inspect)
• Giới hạn tài khoản — Xem giới hạn gửi hàng tháng tùy chỉnh

Các nhãn trong ngoặc đơn ở trên (validate, optimize, inspect) là các thẻ sản phẩm được sử dụng bởi lọc thẻ. Mọi khả năng khác được đăng ký dưới thẻ send.

[!NOTE] Các công cụ bị giới hạn ở thao tác đọc và cập nhật — không có thao tác xóa nào được hiển thị, điều này giữ cho phạm vi ảnh hưởng của một hành động ngoài ý muốn ở mức nhỏ. Xem Cân nhắc bảo mật.

Cách thức hoạt động

Máy chủ được điều khiển bởi OpenAPI. Khi khởi động, nó phân tích cú pháp một đặc tả OpenAPI đi kèm của Mailgun và đăng ký một danh sách cho phép được tuyển chọn các điểm cuối dưới dạng công cụ MCP, tạo lược đồ đầu vào của mỗi công cụ (qua Zod) từ đặc tả. Mỗi công cụ được chú thích bằng một thẻ sản phẩm Mailgun (send, validate, optimize, hoặc inspect). Tất cả các công cụ phù hợp được đăng ký trước — không có tải lười biếng hoặc theo yêu cầu. Lọc thẻ được áp dụng khi khởi động để xác định phạm vi những công cụ nào được đăng ký, do đó một quy trình làm việc nhất định chỉ có thể hiển thị các sản phẩm cần thiết.

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

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

Cài đặt

Máy chủ được xuất bản lên npm dưới dạng @mailgun/mcp-server và chạy qua stdio. Hầu hết các ứng dụng khách có thể khởi chạy nó theo yêu cầu với npx, vì vậy không cần cài đặt toàn cục. Trong mỗi đoạn mã bên dưới, thay thế YOUR-mailgun-api-key bằng một khóa từ cài đặt bảo mật API Mailgun của bạn.

[!TIP] Nếu tài khoản của bạn được lưu trữ ở khu vực EU của Mailgun, hãy thêm "MAILGUN_API_REGION": "eu" vào khối env (hoặc -e MAILGUN_API_REGION=eu trên CLI). Nó mặc định là us.

Claude Code

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

Sau đó chạy /mcp trong Claude Code để xác nhận máy chủ mailgun đã được kết nối.

Claude Desktop

Mở Settings → Developer → Edit Config, hoặc chỉnh sửa trực tiếp tệp:

• 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

Mở bảng lệnh và chọn Cursor Settings → MCP → Add new global MCP server, sau đó thêm:

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

Thêm phần sau vào settings.json của bạn:

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

Thêm vào ~/.gemini/settings.json:

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

Cấu hình

Biến môi trường

Biến	Bắt buộc	Mặc định	Mô tả
MAILGUN_API_KEY	Có	—	Khóa API Mailgun của bạn
MAILGUN_API_REGION	Không	us	Khu vực API: us hoặc eu
MAILGUN_API_HOSTNAME	Không	(suy ra từ khu vực)	Ghi đè tên máy chủ API (ví dụ: api.eu.mailgun.net). Được ưu tiên hơn khu vực.
MAILGUN_MCP_TAGS	Không	(tất cả)	Các thẻ sản phẩm được phân tách bằng dấu phẩy để kích hoạt. Tương đương với --tags. Cờ CLI được ưu tiên.

Tùy chọn CLI

Truyền cờ sau tên gói trong args của ứng dụng khách (ví dụ: ["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"]).

Cờ	Mô tả
--tags <list>	Các thẻ sản phẩm được phân tách bằng dấu phẩy để kích hoạt (mặc định: tất cả). Hợp lệ: send, validate, optimize, inspect.
--list-tags	In các giá trị thẻ hợp lệ và thoát.
--help, -h	Hiển thị cách sử dụng và thoát.

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ác công cụ xác thực cho một quy trình làm việc không cần khả năng gửi.

Các thẻ hợp lệ: send, validate, optimize, inspect. Khi không được 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 hợp đang hoạt động.

Qua cờ CLI — truyền --tags trong args của cấu hình ứng dụng 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 đều có mặt):

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

[!TIP] Chạy tệp nhị phân với --list-tags để in các giá trị thẻ được hỗ trợ, hoặc --help để xem cách sử dụng đầy đủ. Các 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.

Lời nhắc mẫu

Gửi một 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] Một số ứng dụng khách MCP yêu cầu gói trả phí để gọi các công cụ gửi dữ liệu. Nếu việc gửi thất bại một cách âm thầm, hãy kiểm tra gói của ứng dụng 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: alice@example.com, bob@example.com.

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 xét Cài đặt Theo dõi

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

Xác thực Địa chỉ Email

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

Kiểm tra Vị trí Hộp thư đến (Tối ưu hóa)

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

Xem trước Email (Kiểm tra)

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

Phát triển

Chạy từ mã nguồn

Máy chủ được viết bằng TypeScript. Sao chép, cài đặt, xây dựng và kiểm tra:

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

npm run build biên dịch src/ thành dist/ và sao chép đặc tả OpenAPI đi kèm. Trỏ ứng dụng khách MCP của bạn đến điểm vào đã xây dựng thay vì npx (sử dụng đường dẫn tuyệt đối):

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

Kiểm tra trực tiếp trong khi chỉnh sửa

Máy chủ MCP là các tiến trình stdio chạy dài không tự động tải lại, vì vậy vòng lặp là: xây dựng lại khi lưu, sau đó kết nối lại ứng dụng khách để nhận các thay đổi.

1. Chạy npm run build một lần để dist/openapi.yaml sẵn sàng.

2. Giữ trình biên dịch TypeScript chạy để xây dựng lại dist/ mỗi khi lưu:

   npx tsc --watch
   

3. Trỏ một ứng dụng khách MCP riêng biệt (hoặc MCP Inspector, bên dưới) đến dist/mailgun-mcp.js. Sau khi thay đổi, khởi động lại phiên ứng dụng khách MCP để tải bản dựng mới.

Kiểm tra với MCP Inspector

MCP Inspector cho phép bạn thực hành các công cụ mà không cần ứng dụng khách đầy đủ. Xây dựng trước, sau đó khởi chạy nó với máy chủ đã xây dựng:

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

Mở giao diện Inspector, nhấp Connect, sau đó sử dụng List Tools để xác minh máy chủ đang hoạt động. Để kiểm tra một bộ công cụ đã lọc, thêm cờ sau đường dẫn máy chủ:

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

Hook tiền cam kết

npm install cài đặt một hook git tiền cam kết (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 thể sửa hoặc không khớp đồng bộ phiên bản bị từ chối. Nếu bạn đã có một bản sao cục bộ trước thay đổi này, hã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 một điểm cuối mới, nếu bạn sử dụng một chuỗi thuần túy cho định nghĩa của nó, nó sẽ mặc định được gắn thẻ với loại sản phẩm send trong trường _meta. Nếu bạn muốn gắn thẻ nó là một 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ờ được hiển thị 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 cá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. Tất cả 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 các dịch vụ bên thứ ba ngoài API Mailgun.

Quyền của khóa API

Sử dụng khóa API Mailgun chuyên dụng với các quyền được giới hạn chỉ cho các thao tác bạn cần. Máy chủ hiển thị các 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 ngoài ý 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 nhiễ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 có ý đị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 xét các 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 các ngữ cảnh lời nhắc không đáng tin cậy.

URL Webhook

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

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

Tất cả cá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ố trường hợp 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ủ của riêng nó 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 các đóng góp! Vui lòng gửi Pull Request hoặc mở một Issue.