Mailgun MCP Server

공식

Mailgun API와 상호작용합니다.

GitHub

문서

Mailgun MCP 서버

개요

AI 에이전트가 이메일 전송, 전달 가능성 진단, 계정 운영 관리를 실용적이고 워크플로 중심의 인터페이스로 수행할 수 있도록 해주는 Mailgun용 모델 컨텍스트 프로토콜(MCP) 서버입니다.

참고: 이 MCP 서버는 사용자의 로컬 머신에서 실행됩니다. Mailgun은 현재 이 서버의 호스팅 버전을 제공하지 않습니다.

기능

메시징 — 이메일 전송, 저장된 메시지 조회, 메시지 재전송
도메인 — 도메인 세부 정보 보기, DNS 구성 확인, 추적 설정 관리(클릭, 열기, 수신 거부)
웹훅 — 이벤트 웹훅 나열, 생성, 업데이트, 삭제
라우트 — 인바운드 이메일 라우팅 규칙 보기 및 업데이트
메일링 리스트 — 메일링 리스트 및 해당 멤버 생성 및 관리
템플릿 — 버전 관리가 포함된 이메일 템플릿 생성 및 관리
분석 — 전송 지표, 사용량 지표, 로그 조회
통계 — 도메인, 태그, 제공자, 기기, 국가별 집계 통계 보기
제한 — 반송, 수신 거부, 불만, 허용 목록 항목 보기
IP 및 IP 풀 — IP 할당 및 전용 IP 풀 구성 보기
반송 분류 — 반송 유형 및 전달 문제 분석

사전 요구 사항

Node.js (v20.12 이상)
Mailgun 계정 및 API 키

빠른 시작

구성

MCP 클라이언트 구성에 다음을 추가하세요:

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

환경 변수

변수	필수	기본값	설명
`MAILGUN_API_KEY`	예	—	Mailgun API 키
`MAILGUN_API_REGION`	아니오	`us`	API 리전: `us` 또는 `eu`
`MAILGUN_MCP_TAGS`	아니오	(전체)	활성화할 쉼표로 구분된 제품 태그. `--tags`와 동일합니다. CLI 플래그가 우선합니다.

태그 필터링

서버가 등록하는 도구를 하나 이상의 Mailgun 제품 태그로 범위를 지정할 수 있습니다. 이는 모델에 표시되는 도구 세트를 좁히는 데 유용합니다. 예를 들어 전송 기능이 필요하지 않은 워크플로에 유효성 검사 도구만 노출하는 경우입니다.

유효한 태그: send, validate, optimize, inspect. 지정하지 않으면 모든 도구가 등록됩니다(현재 기본값).

필터링은 OR 의미를 사용합니다: 도구의 태그 중 하나라도 활성 세트에 있으면 해당 도구가 등록됩니다.

CLI 플래그 사용 — MCP 클라이언트 구성의 args에 --tags을 전달합니다:

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

환경 변수 사용 — MAILGUN_MCP_TAGS을 설정합니다(둘 다 있는 경우 CLI 플래그가 우선):

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

검색 가능성 — 지원되는 태그 값을 출력하려면 --list-tags을, 전체 사용법을 보려면 --help을 사용하여 바이너리를 실행합니다. 알 수 없는 태그는 시작 시 명확한 오류 메시지와 함께 거부됩니다.

클라이언트별 구성 경로

Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows): %APPDATA%/Claude/claude_desktop_config.json
Claude Code: claude mcp add 실행 또는 ~/.claude.json 편집

샘플 프롬프트

이메일 전송

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

참고: 일부 MCP 클라이언트는 데이터를 전송하는 도구를 호출하기 위해 유료 플랜이 필요합니다. 전송이 자동으로 실패하면 클라이언트의 플랜을 확인하세요.

전송 통계 가져오기 및 시각화

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

템플릿 관리

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

전달 가능성 조사

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

DNS 문제 해결

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

제한 사항 검토

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

라우팅 규칙 관리

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

메일링 리스트 생성

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

도메인 비교

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

지역별 참여도

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

추적 설정 검토

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

개발

소스에서 실행하려면 리포지토리를 복제하고 node를 직접 사용합니다:

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

MCP 클라이언트 구성에서 npx 명령을 다음으로 바꿉니다:

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

사전 커밋 훅

npm install은 (husky를 통해) git 사전 커밋 훅을 설치하여 스테이징된 TypeScript/JavaScript 파일에 대해 oxlint --fix 및 oxfmt를 실행하고 npm run check:versions을 실행합니다. 수정 가능한 문제는 자동으로 수정되어 다시 스테이징되며, 수정 불가능한 린트 오류나 버전 동기화 불일치를 유발하는 커밋은 거부됩니다. 이 변경 전에 이미 로컬 클론이 있었다면 npm install을 한 번 실행하여 훅을 설치하세요.

엔드포인트 추가에 대한 참고 사항

새 엔드포인트를 추가할 때 정의에 일반 문자열을 사용하면 기본적으로 _meta 필드에서 send 제품 유형으로 태그가 지정됩니다. 다른 제품으로 태그를 지정하려면 EndpointEntry 유형의 객체 버전을 사용하세요.

보안 고려 사항

API 키 격리

Mailgun API 키는 환경 변수로 전달되며 AI 모델 자체에는 절대 노출되지 않습니다. MCP 서버 프로세스가 요청을 인증하는 데만 사용됩니다. 서버는 API 키, 요청 매개변수 또는 응답 데이터를 기록하지 않습니다.

로컬 실행

서버는 사용자의 로컬 머신에서 실행됩니다. Mailgun API와의 모든 통신은 TLS 인증서 유효성 검사가 적용된 HTTPS를 통해 이루어집니다. Mailgun API 외의 타사 서비스로는 데이터가 전송되지 않습니다.

API 키 권한

필요한 작업에만 범위가 지정된 권한을 가진 전용 Mailgun API 키를 사용하세요. 서버는 읽기 및 업데이트 작업을 노출하지만 삭제 작업은 노출하지 않으므로 의도하지 않은 작업의 영향 범위를 제한합니다.

속도 제한

서버는 클라이언트 측 속도 제한을 구현하지 않습니다. AI의 각 도구 호출은 Mailgun API 요청으로 직접 변환됩니다. 서버는 남용을 방지하기 위해 Mailgun의 서버 측 속도 제한에 의존합니다. 이러한 제한을 초과하는 요청은 AI 어시스턴트에게 오류를 반환합니다.

프롬프트 인젝션

모든 MCP 서버와 마찬가지로, 조작되거나 적대적인 프롬프트가 AI 어시스턴트를 속여 의도하지 않은 작업(예: 추적 설정 수정 또는 메일링 리스트 멤버 읽기)을 호출하게 할 수 있습니다. 특히 신뢰할 수 없는 프롬프트 컨텍스트에서는 작업을 승인하기 전에 AI 어시스턴트의 도구 호출 확인을 검토하세요.

웹훅 URL

웹훅 생성 및 업데이트 작업은 AI 어시스턴트를 통해 제공된 임의의 URL을 허용합니다. MCP 서버는 추가 유효성 검사 없이 이러한 URL을 Mailgun API에 전달합니다. Mailgun은 웹훅 대상을 검증할 책임이 있습니다. AI 어시스턴트가 의도하지 않은 내부 또는 민감한 주소로 웹훅 URL을 설정하지 않도록 하세요.

입력 유효성 검사

모든 도구 매개변수는 Zod 스키마를 사용하여 Mailgun OpenAPI 사양에 대해 유효성이 검사됩니다. 그러나 유효성 검사는 OpenAPI 사양의 정확성에 의존하며, 일부 엣지 케이스 매개변수는 허용적인 유효성 검사로 대체될 수 있습니다. Mailgun API는 추가 보호 계층으로 자체 서버 측 유효성 검사를 수행합니다.

디버깅

MCP 서버는 stdio를 통해 통신합니다. 문제 해결은 MCP 디버깅 가이드를 참조하세요.

라이선스

Apache 2.0 — 자세한 내용은 LICENSE를 참조하세요.

기여

기여를 환영합니다! Pull Request를 제출하거나 Issue를 열어주세요.