# naver-mail-mcp

[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![도구 30개](https://img.shields.io/badge/도구-30개_(Gmail_MCP_호환)-blue.svg)](#도구-gmail-mcp와-같은-이름)
[![MCP](https://img.shields.io/badge/MCP-Streamable_HTTP_·_stdio-purple.svg)](https://modelcontextprotocol.io)

**AI 에이전트가 지메일처럼 네이버 메일도 읽고, 요약하고, 답장하게 해 주는 MCP 서버입니다.**

Claude, Grok, Meta Muse, ChatGPT, Codex에 연결하면 "이번 주 중요한 메일 요약해줘", "카드 결제 내역 메일만 모아줘", "이 메일에 회신해줘"가 네이버 메일에서도 됩니다.
도구 이름과 사용법이 **Gmail MCP와 같아서**, 지메일로 쓰던 에이전트 흐름을 그대로 쓸 수 있습니다.

[English](README.en.md)

<p align="center"><img src="docs/demo.gif" width="640" alt="AI 비서가 네이버 메일에서 중요한 메일을 찾아 요약하고 답장하는 예시"></p>
<p align="center"><sub>예시 화면 (가상의 메일)</sub></p>

> 네이버의 공식 서비스가 아닙니다. 네이버 메일이 제공하는 IMAP/SMTP로 동작합니다.

## 무엇이 다른가

| | 이 프로젝트 | 다른 네이버 메일 MCP들 |
| --- | :---: | :---: |
| 검색·읽기·첨부 | ✅ | ✅ |
| 지메일 검색 문법 (`from:` `newer_than:7d` `has:attachment` …) | ✅ | 일부 |
| 대화(스레드) 묶어 보기 | ✅ | 일부 |
| 답장·전체 답장·전달 | ✅ | ❌ |
| 임시보관함 만들기·고치기·보내기 | ✅ | 일부 |
| 정리 (메일함 이동, 별표, 읽음, 휴지통, 스팸) | ✅ | ❌ |
| Gmail MCP와 같은 도구 이름·입력 | ✅ | ❌ |
| 클라우드 에이전트 연결 (Muse·Grok·Claude 앱, 설치 없이 주소만) | ✅ | 대부분 PC 전용 |
| 한국어 인코딩 메일 (EUC-KR, `ks_c_5601-1987`, `cp949`) | ✅ | — |

## 시작하기

### 1. 네이버 메일 준비 (한 번만, 약 3분)

연결하려면 **2단계 인증이 필수**입니다. 평소 로그인 비밀번호가 아니라, 2단계 인증을 켜야 만들 수 있는 **애플리케이션 비밀번호**로 연결합니다.

**① 2단계 인증 켜기**
1. 네이버 로그인 → 오른쪽 위 프로필 → **네이버 ID** (또는 [nid.naver.com](https://nid.naver.com))
2. **보안설정** → **2단계 인증** → **설정하기**
3. 휴대폰 번호(또는 네이버 앱)로 본인 확인을 마치면 켜집니다. 이미 켜져 있으면 ②로 넘어갑니다.

**② 애플리케이션 비밀번호 만들기**
1. **네이버 ID → 보안설정 → 2단계 인증 → 관리** (본인 확인을 한 번 더 할 수 있음)
2. 아래쪽 **애플리케이션 비밀번호 관리**에서 종류를 고르고 **생성하기**. 종류는 아무거나(예: Windows, 기타) 괜찮습니다.
3. 나온 비밀번호를 복사해 둡니다. **창을 닫으면 다시 볼 수 없습니다.** 잃어버리면 새로 만들면 됩니다.

**③ POP3/IMAP 설정에서 IMAP 켜기**
1. [네이버 메일](https://mail.naver.com) → 왼쪽 아래 **환경설정** (톱니바퀴)
2. **POP3/IMAP 설정** 탭 → **IMAP/SMTP 설정**
3. **IMAP/SMTP 사용: 사용함** → **저장**. POP3는 켤 필요가 없습니다.

네이버는 메뉴 이름·위치를 가끔 바꿉니다. 메뉴가 안 보이면 네이버 ID 페이지에서 "애플리케이션 비밀번호"를 검색하세요.

### 2. 연결하기 (쉬운 순서)

#### 방법 A. 주소만 넣기 — 추천, 설치 없음

공개 서버 주소: **`https://naver-mail-mcp.yeonuunim521.workers.dev/mcp`**

| 에이전트 | 넣는 곳 |
| --- | --- |
| Claude (웹·데스크톱·모바일) | 설정 → 커넥터 → 커스텀 커넥터 추가 |
| Grok | grok.com/connectors → New Connector → Custom |
| Meta Muse | 설정에서 커넥터 URL 추가, 또는 대화창에 주소를 주고 "연결해줘" |
| ChatGPT | 설정 → 앱/커넥터 → 개발자 모드에서 커스텀 커넥터 추가 |
| Claude Code | `claude mcp add --transport http naver-mail https://naver-mail-mcp.yeonuunim521.workers.dev/mcp` 후 `/mcp`에서 로그인 |
| Codex | `codex mcp add naver-mail --url https://naver-mail-mcp.yeonuunim521.workers.dev/mcp` 후 `codex mcp login naver-mail` |

주소를 넣으면 로그인 화면이 열립니다. **네이버 아이디**와 **애플리케이션 비밀번호**를 넣으면 끝입니다.

- 같은 서비스(예: Claude 앱)라면 PC·태블릿·폰 어디서든 한 번만 로그인하면 됩니다.
- Claude Code나 Codex에는 "네이버 메일 MCP 설치해줘. 주소는 https://naver-mail-mcp.yeonuunim521.workers.dev/mcp, 이름은 naver-mail"이라고만 해도 AI가 설치합니다. 로그인만 직접 하세요.

#### 방법 B. 내 PC에서 실행 — 비밀번호가 내 컴퓨터 밖으로 안 나감

Node.js 20 이상이 필요하고, Claude Desktop·Claude Code·Codex 같은 PC 프로그램에서만 쓸 수 있습니다.

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "naver-mail": {
      "command": "npx",
      "args": ["-y", "naver-mail-mcp"],
      "env": { "NAVER_ID": "내아이디", "NAVER_APP_PASSWORD": "애플리케이션비밀번호" }
    }
  }
}
```

Claude Code: `claude mcp add naver-mail -e NAVER_ID=내아이디 -e NAVER_APP_PASSWORD=앱비밀번호 -- npx -y naver-mail-mcp`

#### 방법 C. 내 서버 만들기 — 클라우드 에이전트 + 내 서버

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/CapyKkuing/naver-mail-mcp)

버튼을 누르면 내 Cloudflare 계정(무료로 됨)에 똑같은 서버가 만들어집니다. 다 되면 나오는 `https://naver-mail-mcp.<내 계정>.workers.dev/mcp`를 방법 A처럼 넣으면 됩니다.

- `ALLOWED_USERS`에 내 네이버 아이디를 넣으면 나만 쓸 수 있습니다. 비우면 누구나 자기 계정으로 연결할 수 있습니다.
- 직접 배포하려면: `npm install` → `npx wrangler kv namespace create OAUTH_KV`로 만든 id를 `wrangler.jsonc`에 넣기 → `npx wrangler deploy`

<details>
<summary>고정 토큰 모드 (헤더를 넣을 수 있는 클라이언트용)</summary>

```bash
npx wrangler secret put MCP_BEARER_TOKEN      # 긴 무작위 문자열
npx wrangler secret put NAVER_ID
npx wrangler secret put NAVER_APP_PASSWORD
```

요청 헤더에 `Authorization: Bearer <MCP_BEARER_TOKEN>`를 넣으면 OAuth 없이 위 계정으로 접속합니다.
</details>

## 보안과 개인정보

- **비밀번호:** 로그인할 때 넣은 애플리케이션 비밀번호는 연결된 앱의 토큰으로 암호화되어 저장되고(`@cloudflare/workers-oauth-provider`), 메일을 읽고 보낼 때만 쓰입니다. 평문으로 남기지 않습니다.
- **메일 내용:** 서버에 저장하지 않습니다. 요청이 올 때 네이버에서 읽어 에이전트에 전달할 뿐입니다. 비밀번호와 메일 내용은 로그에 남기지 않습니다.
- **연결 끊기:** 네이버에서 그 애플리케이션 비밀번호를 삭제하면 모든 에이전트에서 즉시 끊깁니다.
- **메일 발송:** 보내기·답장·전달 전에는 사용자에게 확인하라고 에이전트에게 안내합니다.
- **공개 서버가 꺼려지면:** 공개 서버를 쓰는 것은 그 운영자를 믿는다는 뜻입니다. 코드는 모두 이 리포에 공개되어 있고, 불안하면 방법 B(내 PC)나 방법 C(내 서버)를 쓰세요.

## 도구 (Gmail MCP와 같은 이름)

| 분류 | 도구 |
| --- | --- |
| 찾기·읽기 | `search_threads`, `get_thread`, `get_message`, `get_attachment`, `get_profile` |
| 보내기 | `send_message`, `reply`(전체 답장), `forward`(원래 첨부 포함) |
| 임시보관함 | `create_draft`, `update_draft`, `delete_draft`, `list_drafts`, `get_draft` |
| 라벨 | `list_labels`, `create_label`, `update_label`, `delete_label`, `label_message`, `unlabel_message`, `update_message_labels`, `label_thread`, `unlabel_thread` |
| 휴지통·스팸 | `trash_message`, `trash_thread`, `untrash_message`, `untrash_thread`, `mark_message_spam`, `mark_thread_spam`, `unmark_message_spam`, `unmark_thread_spam` |

`get_profile`과 `get_attachment`는 Gmail MCP에는 없는 추가 도구입니다.

### Gmail과 다른 점 (IMAP의 한계)

- **라벨은 메일함입니다.** `INBOX`, `SENT`, `DRAFT`, `TRASH`, `SPAM`은 해당 메일함, 사용자 라벨은 메일함 경로입니다. 한 메일은 한 메일함에만 있으므로 메일함 라벨을 붙이면 **이동**합니다. `STARRED`(중요 표시)와 `UNREAD`(안읽음)는 플래그입니다.
- **메일 ID는 메일함과 UID로 만듭니다.** 메일을 옮기면 ID가 바뀌고, 옮기는 도구가 새 ID를 돌려줍니다. 임시보관 메일을 고칠 때도 ID가 바뀝니다.
- **보관(archive)이 없습니다.** 받은메일함에서 빼려면 다른 메일함 라벨을 붙이세요.
- **대화(thread)는 Message-ID/References 헤더로 묶습니다.** 네이버 IMAP은 헤더 검색이 잘 안 돼서, 메일함마다 최근 1,000통의 헤더를 직접 읽어 찾습니다.
- **낱말 검색**은 제목, 보낸 사람, 본문을 따로 찾아 합칩니다 (네이버 IMAP은 OR·전체 텍스트 검색을 처리하지 못함). `has:attachment`, `filename:`은 메일 구조를 직접 확인하며 메일함마다 최근 3,000통까지 봅니다. 더 오래된 메일은 `after:` 같은 기간 조건을 함께 쓰세요.
- **기본 검색 범위**는 휴지통, 스팸, 임시보관함을 뺀 모든 메일함입니다. `category:` 같은 Gmail 전용 조건은 무시하고 결과의 `warnings`에 알려 줍니다.
- 서명 자동 붙이기와 카테고리 탭은 지원하지 않습니다.

## 실제 네이버 계정에서 확인한 것

2026년 10월, Meta Muse로 연결해 확인했습니다.

- 2단계 인증 + 애플리케이션 비밀번호로 연결
- 계정·안 읽은 메일 수 확인, 최근 메일 요약
- 검색: 한글 낱말(`결제`), 제목(`subject:`), 기간(`newer_than:30d`), 첨부(`has:attachment`, `filename:pdf`), 보낸메일함(`in:sent`)
- 대화 묶어 보기(`get_thread`), 첨부 이름 읽기
- 메일 발송과 보낸메일함 저장

답장·전달·임시보관함·라벨 이동·휴지통은 가짜 메일 서버 통합 테스트로 확인했고, 실제 계정 확인은 진행 중입니다. 문제를 발견하면 [이슈](https://github.com/CapyKkuing/naver-mail-mcp/issues)로 알려 주세요.

## 개발

```bash
npm install
npm test             # 가짜 IMAP/SMTP 서버 통합 테스트 + 단위 테스트
npm run typecheck
npm run dev          # 로컬 Worker: http://localhost:8787/mcp
npm run stdio        # 로컬 stdio (NAVER_ID, NAVER_APP_PASSWORD 환경 변수)
npm run build:stdio  # npm 배포용 dist/stdio.js
```

접속 정보: IMAP `imap.naver.com:993`(SSL), SMTP `smtp.naver.com:465`(SSL). 바뀐 내용은 [CHANGELOG](CHANGELOG.md)에 있습니다.

## 라이선스

MIT