Mailgun

Máy chủ MCP Mailgun

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 thiết thực, hướng đến quy trình làm việc để gửi email, chẩn đoán khả năng gửi thư và quản lý các hoạt động 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. Hiện Mailgun chưa 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 thư đã lưu trữ, gửi lại thư
• 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 và cập nhật webhook sự kiện
• Tuyến — 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ư cùng thành viên
• Mẫu — Tạo, xem và cập nhật mẫu email có quản lý phiên bản
• Phân tích — Truy vấn chỉ số gửi thư, chỉ số sử dụng và nhật ký
• Thống kê — Xem số liệu thống kê tổng hợp theo tên miền, thẻ, nhà cung cấp, thiết bị và quốc gia
• Danh sách chặn — Xem thư bị trả lại, hủy đăng ký, khiếu nại và mục trong danh sách cho phép
• IP và nhóm IP — Xem phân công IP và cấu hình nhóm IP chuyên dụng
• Phân loại thư bị trả lại — Phân tích loại thư bị trả lại và vấn đề gửi thư
• Xác thực — Xác thực khả năng gửi thư và cú pháp của đị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 seed để đánh giá khả năng gửi thư (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 nhiều ứng dụng email (inspect)
• Giới hạn tài khoản — Xem giới hạn gửi thư hàng tháng tùy chỉnh

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

[!NOTE] Các công cụ chỉ hỗ trợ thao tác đọc và cập nhật — không cung cấp thao tác xóa, giúp hạn chế phạm vi ảnh hưởng nếu xảy ra hành động ngoài ý muốn. Xem Các lưu ý về bảo mật.

Cách hoạt động

Máy chủ được điều khiển bởi OpenAPI. Khi khởi động, máy chủ phân tích cú pháp đặc tả OpenAPI Mailgun đi kèm và đăng ký danh sách cho phép gồm các endpoint được tuyển chọn làm công cụ MCP, đồng thời tạo lược đồ đầu vào cho từng công cụ (bằng Zod) từ đặc tả. Mỗi công cụ được gắn thẻ sản phẩm Mailgun (send, validate, optimize hoặc inspect), bộ công cụ chứa công cụ đó và thông tin cho biết công cụ chỉ đọc dữ liệu hay không.

Theo mặc định, máy chủ tải mọi công cụ khi khởi động. Với --tags dynamic, máy chủ tải một tập công cụ cốt lõi nhỏ cùng ba công cụ mà mô hình dùng để tải thêm bộ công cụ khi cần, nhờ đó giữ cho các định nghĩa công cụ gửi đến mô hình ở mức nhỏ. Thay vào đó, bộ lọc thẻ tải một tập công cụ cố định khi khởi động, để quy trình làm việc có thể chỉ hiển thị đúng các sản phẩm cần dùng.

Đ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 phát hành lên npm với tên @mailgun/mcp-server và chạy qua stdio. Hầu hết ứng dụng khách có thể khởi chạy máy chủ theo yêu cầu bằng 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, hãy thay YOUR-mailgun-api-key bằng khóa lấy từ cài đặt bảo mật API Mailgun.

[!TIP] Nếu tài khoản của bạn được lưu trữ tại 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). Giá trị 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 đã 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 nội dung sau vào settings.json:

{
  "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ẻ hoặc bộ công cụ cần tải, phân tách bằng dấu phẩy, hoặc dynamic để dùng các công cụ cốt lõi và tải thêm công cụ theo yêu cầu. Tương đương với --tags. Cờ CLI được ưu tiên hơn.

Tùy chọn CLI

Truyền các 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ẻ hoặc bộ công cụ cần tải, phân tách bằng dấu phẩy (mặc định: tất cả). Giá trị hợp lệ: all, dynamic, core, send, validate, optimize, inspect và các bộ công cụ send.<group>.
--list-tags	In mọi giá trị --tags hợp lệ kèm mô tả rồi thoát.
--help, -h	Hiển thị cách sử dụng rồi thoát.

Bộ công cụ theo yêu cầu

Với --tags dynamic (hoặc MAILGUN_MCP_TAGS=dynamic), máy chủ khởi động cùng các công cụ cốt lõi sau:

Công cụ	Mục đích
post-v3-domain-messages	Gửi email
get-v4-domains	Liệt kê tên miền
get-v4-domains-name	Chi tiết tên miền và bản ghi DNS
put-v4-domains-name-verify	Kiểm tra lại bản ghi DNS của tên miền
get-v3-domains-name-tracking	Cài đặt theo dõi
get_metrics_summary	Tóm tắt các chỉ số gửi thư chính
post-v1-analytics-metrics	Truy vấn chỉ số tài khoản
post-v1-analytics-logs	Truy vấn nhật ký sự kiện
post-v2-bounce-classification-metrics	Chỉ số phân loại thư bị trả lại
get-v3-domain-bounces	Liệt kê thư bị trả lại
get-v3-domain-bounces-address	Tra cứu bản ghi thư bị trả lại
get-v3-domain-unsubscribes	Liệt kê lượt hủy đăng ký
get-v3-domain-complaints	Liệt kê khiếu nại
get-v3-domain-templates	Liệt kê mẫu
validate_email	Xác thực địa chỉ email

Mỗi công cụ thuộc một bộ công cụ. Khi một tác vụ cần đến, mô hình sẽ tải phần còn lại của bộ công cụ đó:

Bộ công cụ	Công cụ	Nội dung
send.messages	3	Gửi email; truy xuất và gửi lại thư đã lưu trữ
send.domains	8	Tên miền, xác minh DNS, hàng đợi gửi thư, cài đặt theo dõi
send.webhooks	4	Webhook tên miền
send.account	8	IP tài khoản, nhóm IP chuyên dụng, giới hạn gửi thư tùy chỉnh
send.message_tags	8	Thẻ thư, thống kê theo thẻ, giới hạn thẻ
send.analytics	12	Thống kê và số liệu tổng hợp, chỉ số và nhật ký phân tích, phân loại thư bị trả lại
send.suppressions	8	Thư bị trả lại, hủy đăng ký, khiếu nại, danh sách cho phép
send.routes	3	Tuyến thư đến
send.lists	8	Danh sách gửi thư và thành viên
send.templates	8	Mẫu và phiên bản mẫu
validate	1	Xác thực địa chỉ email
optimize	1	Kết quả kiểm tra vị trí hộp thư đến
inspect	1	Kết quả kiểm tra xem trước email

Mô hình tải các bộ công cụ bằng ba công cụ bổ sung:

• mailgun_list_toolsets liệt kê mọi bộ công cụ và các công cụ trong đó, đánh dấu công cụ nào đã được tải và công cụ nào làm thay đổi dữ liệu. Nếu được cung cấp tên công cụ, công cụ này sẽ trả về lược đồ đầu vào của công cụ đó.
• mailgun_enable_toolset tải một hoặc nhiều bộ công cụ. Sau đó, máy chủ thông báo cho ứng dụng khách rằng danh sách công cụ đã thay đổi (notifications/tools/list_changed), và các công cụ mới xuất hiện cùng với các công cụ cốt lõi. Phản hồi liệt kê các công cụ mới nhưng không kèm lược đồ đầu vào; lược đồ sẽ có trong danh sách công cụ được cập nhật.
• mailgun_call_tool chạy một công cụ chỉ đọc theo tên, bất kể bộ công cụ của nó đã được tải hay chưa. Đây là phương án dự phòng cho các ứng dụng khách không làm mới danh sách công cụ sau khi có thay đổi. Công cụ này từ chối chạy các công cụ cốt lõi và công cụ làm thay đổi dữ liệu, vì vậy các công cụ đó luôn được gọi riêng.

Các bộ công cụ đã tải sẽ được giữ nguyên cho đến khi ứng dụng khách ngắt kết nối. Tải theo yêu cầu cần ứng dụng khách làm mới danh sách công cụ khi máy chủ thông báo có thay đổi; Claude Code hỗ trợ việc này. Với các ứng dụng khách không hỗ trợ, công cụ mới tải sẽ không xuất hiện: công cụ chỉ đọc vẫn hoạt động thông qua mailgun_call_tool, còn công cụ làm thay đổi dữ liệu cần dùng chế độ mặc định (tất cả công cụ) hoặc --tags, chẳng hạn --tags core,send.templates.

Lọc theo thẻ

Đặt --tags hoặc MAILGUN_MCP_TAGS thành giá trị khác dynamic sẽ tải chính xác các công cụ khớp với giá trị đó khi khởi động, không bao gồm các công cụ tải bộ công cụ. Hãy dùng tùy chọn này để thu hẹp danh sách công cụ hiển thị cho mô hình (ví dụ: chỉ dùng công cụ xác thực cho quy trình làm việc không gửi email).

Các giá trị hợp lệ (chạy --list-tags để xem mô tả):

• all — mọi công cụ (mặc định)
• dynamic — các công cụ cốt lõi, với các bộ công cụ khác được tải theo yêu cầu. Hãy dùng riêng giá trị này; kết hợp với các giá trị khác sẽ khiến quá trình khởi động thất bại.
• core — chỉ các công cụ cốt lõi được liệt kê ở trên
• send, validate, optimize, inspect — mọi công cụ của sản phẩm đó (send bao gồm mọi bộ công cụ send.<group>)
• Mã bộ công cụ, chẳng hạn send.templates

Bộ lọc sử dụng ngữ nghĩa OR: một công cụ được tải nếu khớp với bất kỳ giá trị nào trong danh sách. Ví dụ: core,send.templates tải các công cụ cốt lõi cùng mọi công cụ mẫu.

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 (nếu có cả hai, cờ CLI được ưu tiên):

"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 mọi giá trị hợp lệ, hoặc --help để xem hướng dẫn sử dụng đầy đủ. Các giá trị không xác định sẽ bị từ chối khi khởi động kèm thông báo lỗi rõ ràng.

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

[!NOTE] Một số MCP client 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à không có thông báo, hãy kiểm tra gói của client.

Tìm nạp 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 thư

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 lại danh sách 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.

Mức độ 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.

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í trong hộp thư đến (Optimize)

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 (Inspect)

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 kho lưu trữ, cài đặt, biên dịch và kiểm thử:

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 OpenAPI spec đã đóng gói. Trỏ MCP client đến tệp entry đã biên dịch thay vì npx (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 thử trực tiếp trong khi chỉnh sửa

MCP server là các tiến trình stdio chạy lâu dài và không tự tải lại, vì vậy quy trình là: biên dịch lại khi lưu, sau đó kết nối lại client để nhận các thay đổi.

1. Chạy npm run build một lần để dist/openapi.yaml được thiết lập.

2. Để trình biên dịch TypeScript chạy liên tục để biên dịch lại dist/ mỗi khi lưu:

   npx tsc --watch
   

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

Kiểm thử bằng MCP Inspector

MCP Inspector cho phép bạn chạy thử các công cụ mà không cần client đầy đủ. Trước tiên hãy biên dịch, sau đó khởi chạy Inspector với máy chủ đã biên dịch:

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, rồi dùng List Tools để xác minh máy chủ đang hoạt động. Để kiểm thử một bộ công cụ đã lọc, hãy thêm các 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 pre-commit

npm install cài đặt hook pre-commit của git (thông qua husky), chạy oxlint --fix và oxfmt trên các tệp TypeScript/JavaScript đã đưa vào staging, đồng thời chạy npm run check:versions. Các vấn đề có thể tự sửa sẽ được tự động khắc phục và đưa lại vào staging; các commit gây ra lỗi lint không thể tự sửa hoặc sai lệch đồng bộ phiên bản sẽ bị từ chối. Nếu bạn đã có 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 ý về việc thêm endpoint

Các endpoint được nhóm theo bộ công cụ trong endpointGroups. Một mục chuỗi thông thường lấy thẻ sản phẩm từ bộ công cụ của nó (send.templates → send) và chỉ được xem là chỉ đọc nếu đó là GET. Dùng dạng đối tượng của EndpointEntry để đặt tên công cụ, đánh dấu công cụ là core (được tải khi khởi động ở chế độ động), hoặc đánh dấu POST chỉ truy vấn dữ liệu là readOnly: true.

Các cân nhắc về 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 — khóa này chỉ được tiến trình MCP server sử dụng để 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à có thực thi xác thực chứng chỉ TLS. 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 của khóa API

Hãy dùng khóa API Mailgun chuyên dụng với quyền được giới hạn chỉ ở những thao tác bạn cần. Máy chủ cung cấp các thao tác đọc và cập nhật nhưng không cung cấp thao tác xóa nào, qua đó hạn chế 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 client. Mỗi lần AI gọi công cụ sẽ chuyển 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 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.

Chèn lệnh vào prompt

Cũng như mọi MCP server, một prompt được tạo có chủ đích hoặc mang tính đối kháng có thể lừa trợ lý AI gọi những thao tác bạn không định thực hiện — chẳng hạn như sửa đổi cài đặt theo dõi hoặc đọc thành viên danh sách gửi thư. Hãy xem lại 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 ngữ cảnh prompt không đáng tin cậy.

Tải công cụ và phê duyệt

Mỗi công cụ đều có chú thích MCP readOnlyHint, nhờ đó client có thể phân biệt công cụ chỉ đọc dữ liệu với công cụ thay đổi dữ liệu (ví dụ: khi yêu cầu phê duyệt). mailgun_list_toolsets và mailgun_call_tool chỉ có quyền đọc. mailgun_enable_toolset thay đổi những công cụ mà phiên làm việc nhìn thấy nên không được đánh dấu là chỉ đọc, nhưng nó không bao giờ thay đổi bất cứ điều gì trong Mailgun. mailgun_call_tool chỉ chạy các công cụ chỉ đọc không thuộc bộ công cụ cốt lõi, vì vậy việc phê duyệt công cụ này không bao giờ có thể gửi email hoặc thay đổi cài đặt tài khoản. Các công cụ thay đổi dữ liệu luôn chạy dưới dạng lệnh gọi công cụ riêng.

Tải các bộ công cụ theo yêu cầu giúp giảm lượng thông tin mà mô hình nhìn thấy; đây không phải là cơ chế kiểm soát quyền truy cập, vì mô hình có thể tải bất kỳ bộ công cụ nào. Để giới hạn những công cụ mà máy chủ cung cấp, hãy dùng --tags.

URL webhook

Các thao tác tạo và cập nhật webhook chấp nhận URL tùy ý do trợ lý AI cung cấp. MCP server 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 trỏ đế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ả tham số công cụ đều được xác thực theo đặ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ể dùng phương thức xác thực dễ dãi. API Mailgun tự thực hiện xác thực phía máy chủ như một lớp bảo vệ bổ sung.

Gỡ lỗi

MCP server 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! Bạn có thể gửi Pull Request hoặc mở Issue.