세 가지 연동 방식
MCP server
npx -y @moemail/mcp. 어떤 MCP 클라이언트에서도 stdio로 호출할 수 있는 8개의 도구. 배포할 것도, 계속 띄워 둘 것도 없습니다.
CLI
npm i -g @moemail/cli. 9개의 명령 모두 --json 출력과 의미 있는 종료 코드를 지원하며, 셸 기반 에이전트와 CI 작업을 위해 설계되었습니다.
에이전트 skill
moemail skill install이 SKILL.md를 Claude Code 또는 Codex에 넣어 주므로, 에이전트는 요청받기 전부터 '생성 → 대기 → 읽기 → 삭제' 흐름을 알고 있습니다.
도구 목록
이름은 server가 실제로 등록하는 것과 정확히 같습니다. 에이전트가 실제로 동작하게 만드는 것은 wait_for_email입니다. 최대 90초 동안 대기하고, 시간이 지나면 실패 대신 status: "timeout"을 반환하므로 에이전트는 그냥 다시 호출하면 됩니다.
- create_email
- 메일함을 생성하고
id와address를 반환합니다. 유효 기간은1h,24h,3d또는permanent. - wait_for_email
- 새 메시지가 도착할 때까지 폴링(호출당 ≤ 90초)하고, 없으면 정상적으로 타임아웃합니다.
- list_messages
- 메일함이 받은 메시지 목록(최신순).
- read_message
- 메시지 한 건의 전체 본문과 HTML.
- list_emails
- 이 API 키가 소유한 모든 메일함.
- send_email
- 임시 주소에서 회신(발송 할당량 필요).
- delete_message
- 메시지 한 건 삭제.
- delete_email
- 메일함과 그 안의 모든 내용 삭제.
세션은 이렇게 진행됩니다
인증 코드를 받는 전체 과정을 에이전트가 실제로 수행하는 도구 호출로 보여 줍니다. 호출 4회에, 메일이 도착할 때까지의 폴링 몇 회가 더해집니다.
일회용 주소로 example.com 베타에 가입하고 인증 코드를 알려 줘.
에이전트가 메일함을 만들고 그 주소를 가입 폼에 입력합니다.
→ create_email { "expiry": "1h" }
← { "id": "k3f…", "address": "x7q2m9@moemail.app", "expiresAt": "…T15:04:05.000Z" }그다음 기다립니다. 폴링 한 번이 API 호출 한 번입니다. 여기서는 12초 뒤에 메일이 도착했습니다.
→ wait_for_email { "emailId": "k3f…", "timeoutSec": 90 }
← { "status": "received", "elapsedSec": 12,
"message": { "messageId": "m81…", "from": "no-reply@example.com",
"subject": "Your code is 482913", "receivedAt": "…" } }메시지를 읽고 본문에서 코드를 꺼냅니다.
→ read_message { "emailId": "k3f…", "messageId": "m81…" }
← { "id": "m81…", "from": "no-reply@example.com", "subject": "Your code is 482913",
"content": "Enter 482913 to finish signing up. …", "html": "…", … }마지막으로 메일함을 삭제해 아무것도 남기지 않습니다.
→ delete_email { "emailId": "k3f…" }
← { "success": true, "deleted": "k3f…" }완료했습니다 — 코드는 482913입니다. 메일함은 삭제했습니다.
클라이언트 연결
점으로 표시된 자리에 키를 붙여 넣으세요. mcpServers 블록은 Claude Desktop, Cursor, Windsurf에서 동일합니다. Claude Code와 Codex는 같은 명령을 각자의 형식으로 작성합니다.
{
"mcpServers": {
"moemail": {
"command": "npx",
"args": ["-y", "@moemail/mcp"],
"env": {
"MOEMAIL_API_KEY": "mk_••••••••••••"
}
}
}
}{
"mcpServers": {
"moemail": {
"command": "npx",
"args": ["-y", "@moemail/mcp"],
"env": {
"MOEMAIL_API_KEY": "mk_••••••••••••"
}
}
}
}claude mcp add moemail -e MOEMAIL_API_KEY=mk_•••••••••••• -- npx -y @moemail/mcp[mcp_servers.moemail]
command = "npx"
args = ["-y", "@moemail/mcp"]
env = { MOEMAIL_API_KEY = "mk_••••••••••••" }MoeMail을 직접 호스팅하시나요? 인스턴스를 가리키는 MOEMAIL_API_URL을 추가하세요. 두 패키지 모두 기본값은 moemail.app입니다.
또는 셸에서 바로
같은 API, 에이전트 런타임은 불필요. 모든 명령이 --json을 받으며, 종료 코드 1은 런타임 오류, 2는 설정 또는 인증 오류이므로 스크립트가 '메일이 아직 안 왔다'와 '키가 틀렸다'를 구분할 수 있습니다.
npm i -g @moemail/cli
moemail config set api-key mk_••••••••••••
# 1. a mailbox that lives for an hour
moemail create --expiry 1h --json
# {"id":"k3f…","address":"x7q2m9@moemail.app","expiresAt":"2026-09-02T15:04:05.000Z"}
# 2. block until the verification mail lands (exit 1 on timeout)
moemail wait --email-id k3f… --timeout 120 --json
# {"messageId":"m81…","from":"no-reply@example.com","subject":"Your code is 482913","receivedAt":"…"}
# 3. read it, then clean up
moemail read --email-id k3f… --message-id m81… --json
moemail delete --email-id k3f…한 번만 가르치면 됩니다
CLI에는 skill 파일이 함께 들어 있습니다. 설치하면 일회용 받은편지함이 필요한 작업에서 Claude Code나 Codex가 스스로 moemail을 사용하므로, 매번 절차를 설명할 필요가 없습니다.
moemail skill install # auto-detects Claude Code and Codex
moemail skill install --platform claude # ~/.claude/skills/moemail/SKILL.md
moemail skill install --platform codex # ~/.codex/skills/moemail/SKILL.md키, 할당량, 가격
두 패키지 모두 MoeMail API 키로 인증합니다. 프로필에서 만들면 됩니다 — REST API가 쓰는 것과 같은 키이며, 같은 월간 할당량을 사용합니다.
API 접근은 유료 부가 기능입니다. 기본 플랜에는 무료 호출 한도가 없습니다. 상점에서 MoeCoin으로 API 호출 패키지를 구매하거나 Duke로 업그레이드하세요. 웹 받은편지함 자체는 계속 무료이므로, API에 비용을 내기 전에 메일함이 어떻게 동작하는지 먼저 볼 수 있습니다.
폴링 비용을 감안하세요. wait_for_email의 폴링 한 번, CLI wait의 확인 한 번이 각각 호출 한 번입니다. 일반적인 인증 왕복 — 생성, 대기, 읽기, 삭제 — 은 호출 4회에 폴링 횟수를 더한 것입니다.