Mailgun

Mailgun MCP 서버

개요

AI 에이전트가 이메일 전송, 전달 가능성 진단, 계정 운영 관리를 위한 실용적인 워크플로 중심 인터페이스를 제공하는 Mailgun용 모델 컨텍스트 프로토콜 (MCP) 서버입니다.

[!NOTE] 이 MCP 서버는 사용자의 로컬 머신에서 실행되며 stdio를 통해 통신합니다. Mailgun은 현재 이 서버의 호스팅 버전을 제공하지 않습니다.

기능

• 메시징 — 이메일 전송, 저장된 메시지 조회, 메시지 재전송
• 도메인 — 도메인 세부 정보 보기, DNS 구성 확인, 추적 설정 관리 (클릭, 열람, 수신 거부)
• 웹훅 — 이벤트 웹훅 나열, 생성, 업데이트
• 라우트 — 인바운드 이메일 라우팅 규칙 보기 및 업데이트
• 메일링 리스트 — 메일링 리스트 및 해당 멤버 생성, 보기, 업데이트
• 템플릿 — 버전 관리가 포함된 이메일 템플릿 생성, 보기, 업데이트
• 분석 — 전송 지표, 사용량 지표, 로그 쿼리
• 통계 — 도메인, 태그, 제공업체, 기기, 국가별 집계 통계 보기
• 제한 — 반송, 수신 거부, 불만, 허용 목록 항목 보기
• IP 및 IP 풀 — IP 할당 및 전용 IP 풀 구성 보기
• 반송 분류 — 반송 유형 및 전달 문제 분석
• 유효성 검사 — 전송 전 이메일 주소 전달 가능성 및 구문 유효성 검사 (validate)
• 최적화 (받은 편지함 배치) — 받은 편지함 배치 / 시드 테스트 결과를 조회하여 전달 가능성 측정 (optimize)
• 검사 (이메일 미리보기) — 다양한 클라이언트에서 이메일 렌더링 및 미리보기 테스트 결과 조회 (inspect)
• 계정 한도 — 사용자 지정 월간 전송 한도 보기

위의 괄호 안 레이블(validate, optimize, inspect)은 태그 필터링에서 사용하는 제품 태그입니다. 다른 모든 기능은 send 태그 아래 등록됩니다.

[!NOTE] 도구는 읽기 및 업데이트 작업으로 제한되며 삭제 작업은 노출되지 않으므로 의도하지 않은 작업의 영향 범위가 작게 유지됩니다. 보안 고려 사항을 참조하세요.

작동 방식

서버는 OpenAPI 기반입니다. 시작 시 번들로 제공되는 Mailgun OpenAPI 사양을 구문 분석하고 엔드포인트의 선별된 허용 목록을 MCP 도구로 등록하며, 사양에서 각 도구의 입력 스키마(Zod를 통해)를 생성합니다. 모든 도구에는 Mailgun 제품 태그(send, validate, optimize, 또는 inspect)가 주석으로 추가됩니다. 일치하는 모든 도구는 사전에 등록되며 지연 로딩이나 온디맨드 로딩은 없습니다. 태그 필터링은 시작 시 적용되어 등록될 도구의 범위를 지정하므로, 특정 워크플로에 필요한 제품만 노출할 수 있습니다.

사전 요구 사항

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

설치

서버는 @mailgun/mcp-server로 npm에 게시되며 stdio를 통해 실행됩니다. 대부분의 클라이언트는 npx를 사용하여 필요 시 실행할 수 있으므로 전역으로 설치할 필요가 없습니다. 아래 각 스니펫에서 YOUR-mailgun-api-key을 Mailgun API 보안 설정의 키로 교체하세요.

[!TIP] 계정이 Mailgun의 EU 리전에 호스팅된 경우 env 블록(또는 CLI의 -e MAILGUN_API_REGION=eu)에 "MAILGUN_API_REGION": "eu"을 추가하세요. 기본값은 us입니다.

Claude Code

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

그런 다음 Claude Code에서 /mcp를 실행하여 mailgun 서버가 연결되었는지 확인합니다.

Claude Desktop

설정 → 개발자 → 구성 편집을 열거나 파일을 직접 편집합니다:

• 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

명령 팔레트를 열고 Cursor 설정 → MCP → 새 전역 MCP 서버 추가를 선택한 후 추가합니다:

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

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

~/.gemini/settings.json에 추가합니다:

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

구성

환경 변수

변수	필수	기본값	설명
MAILGUN_API_KEY	예	—	Mailgun API 키
MAILGUN_API_REGION	아니요	us	API 리전: us 또는 eu
MAILGUN_API_HOSTNAME	아니요	(리전에서 파생)	API 호스트 이름 재정의 (예: api.eu.mailgun.net). 리전보다 우선합니다.
MAILGUN_MCP_TAGS	아니요	(전체)	활성화할 쉼표로 구분된 제품 태그. --tags와 동일합니다. CLI 플래그가 우선합니다.

CLI 옵션

클라이언트의 args에서 패키지 이름 뒤에 플래그를 전달합니다 (예: ["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"]).

플래그	설명
--tags <list>	활성화할 쉼표로 구분된 제품 태그 (기본값: 전체). 유효한 값: send, validate, optimize, inspect.
--list-tags	유효한 태그 값을 출력하고 종료합니다.
--help, -h	사용법을 표시하고 종료합니다.

태그 필터링

서버가 등록하는 도구를 하나 이상의 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"
}

[!TIP] --list-tags을 사용하여 바이너리를 실행하면 지원되는 태그 값을 출력하고, --help을 사용하면 전체 사용법을 출력합니다. 알 수 없는 태그는 시작 시 명확한 오류 메시지와 함께 거부됩니다.

샘플 프롬프트

이메일 보내기

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] 일부 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: alice@example.com, bob@example.com.

도메인 비교하기

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.

이메일 주소 유효성 검사하기

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

받은 편지함 배치 확인하기 (최적화)

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

이메일 미리보기 (검사)

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

개발

소스에서 실행

서버는 TypeScript로 작성되었습니다. 복제, 설치, 빌드 및 테스트:

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/를 dist/으로 컴파일하고 번들로 제공되는 OpenAPI 사양을 복사합니다. MCP 클라이언트가 npx 대신 빌드된 진입점을 가리키도록 합니다 (절대 경로 사용):

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

편집 중 실시간 테스트

MCP 서버는 핫 리로드되지 않는 장기 실행 stdio 프로세스이므로, 루프는 다음과 같습니다: 저장 시 재빌드한 다음 클라이언트를 다시 연결하여 변경 사항을 적용합니다.

1. dist/openapi.yaml이 준비되도록 npm run build를 한 번 실행합니다.

2. 저장할 때마다 dist/를 재빌드하도록 TypeScript 컴파일러를 계속 실행합니다:

   npx tsc --watch
   

3. 별도의 MCP 클라이언트(또는 아래의 MCP Inspector)가 dist/mailgun-mcp.js를 가리키도록 합니다. 변경 후 MCP 클라이언트 세션을 다시 시작하여 새 빌드를 로드합니다.

MCP Inspector로 테스트하기

MCP Inspector를 사용하면 전체 클라이언트 없이 도구를 실행할 수 있습니다. 먼저 빌드한 다음 빌드된 서버에 대해 실행합니다:

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

Inspector UI를 열고 연결을 클릭한 다음 도구 나열을 사용하여 서버가 작동하는지 확인합니다. 필터링된 도구 세트를 테스트하려면 서버 경로 뒤에 플래그를 추가합니다:

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

사전 커밋 훅

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 외에 제3자 서비스로 데이터가 전송되지 않습니다.

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를 열어주세요.