Mailgun

공식

Mailgun API와 상호작용합니다.

GitHub

Mailgun MCP(으)로 무엇을 할 수 있나요?

이메일 보내기 — 선택한 발신 도메인과 주소로 이메일을 보내도록 어시스턴트에게 요청합니다.
주소 검증 — 전송 전에 validate로 이메일 주소의 구문과 전달 가능성을 확인합니다.
받은편지함 배치 확인 — optimize로 시드 테스트 결과를 가져와 메시지가 제공업체별로 어디에 도착했는지 요약합니다.
렌더링 미리보기 — inspect로 이메일 미리보기 결과를 가져와 여러 클라이언트에서 메시지가 어떻게 렌더링되는지 확인합니다.
전달 가능성 조사 — 도메인의 반송 분류 통계, 수신 거부 및 불만을 검토합니다.
템플릿 및 목록 관리 — 구성원이 포함된 이메일 템플릿과 메일링 목록을 만들거나 업데이트합니다.

문서

Mailgun MCP 서버

개요

Mailgun용 Model Context Protocol (MCP) 서버로, AI 에이전트가 이메일을 보내고, 전달 가능성을 진단하고, 계정 작업을 관리할 수 있도록 실용적이고 워크플로 중심적인 인터페이스를 제공합니다.

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

기능

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

위 레이블(validate, optimize, inspect)은 태그 필터링에 사용되는 제품 태그입니다. 그 밖의 모든 기능은 send 태그에 등록되며, 이 태그는 send.<group>개의 도구 세트로 나뉩니다.

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

작동 방식

이 서버는 OpenAPI 기반입니다. 시작 시 번들로 제공되는 Mailgun OpenAPI 사양을 파싱하고, 엄선된 엔드포인트 허용 목록을 MCP 도구로 등록하며, 사양에서 각 도구의 입력 스키마를 생성합니다(Zod 사용). 각 도구에는 Mailgun 제품 태그(send, validate, optimize 또는 inspect), 소속 도구 세트, 데이터 읽기 전용 여부가 주석으로 표시됩니다.

기본적으로 서버는 시작 시 모든 도구를 불러옵니다. --tags dynamic를 사용하면 작은 핵심 도구 세트와 모델이 필요에 따라 더 많은 도구 세트를 불러오는 데 사용하는 도구 세 개를 불러오므로, 모델에 전달되는 도구 정의의 크기를 줄일 수 있습니다. 태그 필터링은 대신 시작 시 고정된 도구 세트를 불러오므로, 특정 워크플로에 필요한 제품만 정확히 노출할 수 있습니다.

사전 요구 사항

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

설치

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

[!TIP] 계정이 Mailgun의 EU 리전에서 호스팅되는 경우 "MAILGUN_API_REGION": "eu"을 env 블록에 추가하거나(CLI에서는 -e 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

Settings → Developer → Edit Config를 열거나 파일을 직접 편집하세요.

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 Settings → MCP → Add new global MCP server를 선택한 다음 다음을 추가하세요.

{
  "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`	아니요	(전체)	불러올 태그 또는 도구 세트를 쉼표로 구분해 지정하거나, 필요에 따라 더 불러오는 핵심 도구에는 `dynamic`를 지정합니다. `--tags`과 동일합니다. CLI 플래그가 우선합니다.

CLI 옵션

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

플래그	설명
`--tags <list>`	불러올 태그 또는 도구 세트를 쉼표로 구분해 지정합니다(기본값: 전체). 유효한 값: `all`, `dynamic`, `core`, `send`, `validate`, `optimize`, `inspect` 및 `send.<group>` 도구 세트.
`--list-tags`	설명과 함께 유효한 `--tags` 값을 모두 출력하고 종료합니다.
`--help`, `-h`	사용법을 표시하고 종료합니다.

필요에 따른 도구 세트 로드

--tags dynamic(또는 MAILGUN_MCP_TAGS=dynamic)을 사용하면 서버는 다음 핵심 도구로 시작합니다.

도구	용도
`post-v3-domain-messages`	이메일 전송
`get-v4-domains`	도메인 나열
`get-v4-domains-name`	도메인 세부 정보 및 DNS 레코드
`put-v4-domains-name-verify`	도메인의 DNS 레코드 다시 확인
`get-v3-domains-name-tracking`	추적 설정
`get_metrics_summary`	주요 전송 지표 요약
`post-v1-analytics-metrics`	계정 지표 조회
`post-v1-analytics-logs`	이벤트 로그 조회
`post-v2-bounce-classification-metrics`	반송 분류 지표
`get-v3-domain-bounces`	반송 목록
`get-v3-domain-bounces-address`	반송 레코드 조회
`get-v3-domain-unsubscribes`	수신 거부 목록
`get-v3-domain-complaints`	불만 목록
`get-v3-domain-templates`	템플릿 목록
`validate_email`	이메일 주소 검증

모든 도구는 도구 세트에 속합니다. 작업에 필요하면 모델이 나머지 도구 세트를 불러옵니다.

도구 세트	도구 수	내용
`send.messages`	3	이메일 전송, 저장된 메시지 조회 및 재전송
`send.domains`	8	도메인, DNS 검증, 전송 대기열, 추적 설정
`send.webhooks`	4	도메인 웹훅
`send.account`	8	계정 IP, 전용 IP 풀, 사용자 지정 전송 한도
`send.message_tags`	8	메시지 태그, 태그별 통계, 태그 한도
`send.analytics`	12	통계 및 집계, 분석 지표 및 로그, 반송 분류
`send.suppressions`	8	반송, 수신 거부, 불만, 허용 목록
`send.routes`	3	수신 라우트
`send.lists`	8	메일링 리스트 및 구성원
`send.templates`	8	템플릿 및 템플릿 버전
`validate`	1	이메일 주소 검증
`optimize`	1	받은편지함 배치 테스트 결과
`inspect`	1	이메일 미리보기 테스트 결과

모델은 다음 세 가지 추가 도구를 사용해 도구 세트를 불러옵니다.

**mailgun_list_toolsets**는 모든 도구 세트와 해당 도구를 나열하고, 어떤 도구 세트가 불러와졌는지와 어떤 도구가 데이터를 변경하는지 표시합니다. 도구 이름을 지정하면 대신 해당 도구의 입력 스키마를 반환합니다.
**mailgun_enable_toolset**은 하나 이상의 도구 세트를 불러옵니다. 그러면 서버는 도구 목록이 변경되었음을 클라이언트에 알리고(notifications/tools/list_changed), 새 도구가 핵심 도구와 함께 표시됩니다. 응답에는 입력 스키마 없이 새 도구가 나열되며, 입력 스키마는 업데이트된 도구 목록에 포함됩니다.
**mailgun_call_tool**는 도구 세트가 불러와졌는지와 관계없이 이름으로 읽기 전용 도구를 실행합니다. 변경 후 도구 목록을 새로 고치지 않는 클라이언트를 위한 대체 수단입니다. 핵심 도구와 데이터를 변경하는 도구는 실행하지 않으므로, 이러한 도구는 항상 자체 도구 호출로 실행됩니다.

불러온 도구 세트는 클라이언트 연결이 끊길 때까지 유지됩니다. 필요에 따른 로드 기능을 사용하려면 서버가 변경 사항을 알릴 때 도구 목록을 새로 고치는 클라이언트가 필요하며, Claude Code는 이를 지원합니다. 그렇지 않은 클라이언트에서는 새로 불러온 도구가 표시되지 않습니다. 읽기 전용 도구는 mailgun_call_tool을 통해 계속 사용할 수 있지만, 데이터를 변경하는 도구를 사용하려면 기본 설정(모든 도구) 또는 --tags이 필요합니다. 예: --tags core,send.templates.

태그 필터링

--tags 또는 MAILGUN_MCP_TAGS을 dynamic 이외의 값으로 설정하면 로드 도구 없이 일치하는 도구만 시작 시 불러옵니다. 이를 사용해 모델에 표시되는 도구를 제한할 수 있습니다(예: 이메일을 보내지 않는 워크플로에서 검증 도구만 사용).

유효한 값(설명은 --list-tags 실행):

all — 모든 도구(기본값)
dynamic — 핵심 도구와 필요에 따른 나머지 도구 세트. 단독으로 사용하세요. 다른 값과 함께 사용하면 시작 시 오류가 발생합니다.
core — 위에 나열된 핵심 도구만
send, validate, optimize, inspect — 해당 제품의 모든 도구(send은 모든 send.<group> 도구 세트를 포함)
send.templates와 같은 도구 세트 ID

필터링에는 OR 의미 체계가 적용됩니다. 목록의 값 중 하나라도 일치하면 도구가 로드됩니다. 예를 들어 core,send.templates은 핵심 도구와 모든 템플릿 도구를 불러옵니다.

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 사양을 복사합니다. npx 대신 빌드된 진입점을 가리키도록 MCP 클라이언트를 설정하세요(절대 경로 사용).

{
  "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 프로세스이며 핫 리로드를 지원하지 않습니다. 따라서 저장할 때마다 다시 빌드한 다음 클라이언트를 다시 연결해 변경 사항을 적용해야 합니다.

npm run build을 한 번 실행해 dist/openapi.yaml가 준비되도록 합니다.
TypeScript 컴파일러를 계속 실행해 저장할 때마다 dist/를 다시 빌드합니다.
```
npx tsc --watch
```
별도의 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를 열고 Connect를 클릭한 다음 List Tools를 사용해 서버가 작동하는지 확인하세요. 필터링된 도구 세트를 테스트하려면 서버 경로 뒤에 플래그를 추가하세요.

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을 한 번 실행해 훅을 설치하세요.

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

엔드포인트는 endpointGroups에서 도구 세트별로 그룹화됩니다. 일반 문자열 항목은 해당 도구 세트에서 제품 태그를 가져오며(send.templates → send), GET인 경우에만 읽기 전용으로 처리됩니다. EndpointEntry의 객체 형식을 사용하면 도구 이름을 설정하거나, 도구를 core(동적 모드에서 시작 시 로드됨)로 표시하거나, 데이터만 조회하는 POST을 readOnly: true로 표시할 수 있습니다.

보안 고려 사항

API 키 격리

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

로컬 실행

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

API 키 권한

필요한 작업에만 권한이 제한된 전용 Mailgun API 키를 사용하세요. 서버는 읽기 및 업데이트 작업을 제공하지만 삭제 작업은 제공하지 않으므로, 의도하지 않은 작업의 피해 범위가 제한됩니다.

속도 제한

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

프롬프트 인젝션

다른 MCP 서버와 마찬가지로, 조작되었거나 적대적인 프롬프트는 AI 어시스턴트를 속여 의도하지 않은 작업을 호출하게 할 수 있습니다. 예를 들어 추적 설정을 수정하거나 메일링 리스트 구성원을 읽게 할 수 있습니다. 특히 신뢰할 수 없는 프롬프트가 포함된 상황에서는 작업을 승인하기 전에 AI 어시스턴트의 도구 호출 확인 내용을 검토하세요.

도구 로드 및 승인

모든 도구에는 MCP readOnlyHint 주석이 포함되어 있으므로, 클라이언트는 데이터만 읽는 도구와 데이터를 변경하는 도구를 구분할 수 있습니다(예: 승인 요청 시). mailgun_list_toolsets 및 mailgun_call_tool는 읽기 전용입니다. mailgun_enable_toolset은 세션에 표시되는 도구를 변경하므로 읽기 전용으로 표시되지 않지만, Mailgun의 어떤 항목도 변경하지 않습니다. mailgun_call_tool는 핵심 세트에 포함되지 않은 읽기 전용 도구만 실행하므로, 이를 승인해도 이메일을 보내거나 계정 설정을 변경할 수 없습니다. 데이터를 변경하는 도구는 항상 별도의 도구 호출로 실행됩니다.

필요할 때 도구 세트를 로드하면 모델에 표시되는 내용을 줄일 수 있지만, 모델이 어떤 도구 세트든 로드할 수 있으므로 이는 접근 제어가 아닙니다. 서버가 노출하는 도구 자체를 제한하려면 --tags를 사용하세요.

웹훅 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를 등록해 주세요.