korean-mail-mcp
# korean-mail-mcp
Claude Code에서 **네이버·다음 메일을 읽고, 답장·새 메일 초안을 임시보관함에 저장**하는 MCP 서버입니다.
- 메일 검색, 메일 읽기, 첨부 파일 내려받기, 초안 저장(새 메일·답장·전체 답장)을 할 수 있습니다.
- **메일을 발송하지 않습니다.** 초안은 웹메일 임시보관함에서 확인하신 뒤 직접 발송해 주세요.
- 메일 주소와 앱 비밀번호는 사용자 PC에만 저장됩니다. 외부 서버를 거치지 않고 메일 서버에 바로 접속합니다.
- 같은 서비스의 계정을 여러 개 등록할 수 있습니다.
## 준비물
- [Claude Code](https://claude.com/claude-code) (CLI 또는 데스크톱 앱의 Claude Code 모드)
- [Node.js](https://nodejs.org) 22 이상 (LTS 버전 권장)
- 연결할 메일 계정의 **IMAP 사용 설정**과 **앱 비밀번호**
## 설치
터미널(Windows는 PowerShell)에서 아래 명령을 실행해 주세요.
```
npx -y @cpal1828/korean-mail-mcp setup
```
1. **계정 추가**를 선택하고 메일 서비스를 고릅니다.
2. 화면의 준비 단계에 따라 IMAP을 켜고 앱 비밀번호를 만듭니다.
3. 메일 주소와 앱 비밀번호를 입력하면 그 자리에서 접속을 확인합니다.
4. **완료 (저장)**를 선택하면 Claude Code에 등록됩니다.
5. Claude Code를 다시 시작합니다.
계정을 추가하거나, 비밀번호를 바꾸거나, 삭제할 때도 같은 명령을 실행해 주세요. 기존 계정은 그대로 유지됩니다.
### 앱 비밀번호 만들기
**네이버**
1. IMAP 켜기: 네이버 메일 → 환경설정 → POP3/IMAP 설정 → IMAP/SMTP 사용 → '사용함'
2. 앱 비밀번호 만들기(2단계 인증이 꺼져 있으면 먼저 켭니다): 네이버 내정보 → 보안설정 → 2단계 인증 '관리' → 애플리케이션 비밀번호 관리 → '직접 입력'에 10자 이내 이름(예: mailmcp) → 생성
자세한 안내: https://help.naver.com/service/5640/contents/8584?osType=COMMONOS
**다음**
1. IMAP 켜기: 다음 메일 → 환경설정 → IMAP/POP3 → IMAP/SMTP 사용 → '사용함' → 저장
2. 앱 비밀번호 만들기: 다음 회원 → 마이페이지 → 계정 보안 → 앱 비밀번호 → 휴대폰 2차 인증 → 이름 입력(예: mailmcp) → 생성
2025년 12월 1일부터 다음 메일 앱 비밀번호는 다음 회원 마이페이지에서만 만들 수 있습니다. 카카오계정에서 만든 비밀번호는 사용할 수 없습니다.
자세한 안내: https://cs.daum.net/faq/43/9234.html?faqId=31143
앱 비밀번호는 한 번만 표시되므로 바로 복사해 주세요.
## 사용 예
Claude Code에서 평소처럼 요청하시면 됩니다.
- "네이버 메일에서 이번 주에 한국공인회계사회가 보낸 메일 찾아 줘"
- "그 메일 첨부 파일 받아서 내용 정리해 줘"
- "정리한 내용으로 전체 답장 초안 만들어 줘"
계정이 여러 개이고 요청에서 어느 계정인지 분명하지 않으면 Claude가 먼저 여쭙니다.
## 도구
| 도구 | 하는 일 |
|---|---|
| `list_accounts` | 등록된 계정 목록 |
| `list_folders` | 메일함 목록 |
| `search_emails` | 보낸 사람(이름·주소), 제목, 기간, 안 읽음으로 검색(기본 최근 30일) |
| `read_email` | 메일 읽기. 읽음 표시를 남기지 않습니다 |
| `download_attachment` | 첨부 파일을 다운로드 폴더(또는 지정한 폴더)에 저장 |
| `create_draft` | 새 메일·답장 초안을 임시보관함에 저장. 답장은 전체 답장이 기본입니다 |
## 알아 두실 점
- **비밀번호 저장 위치:** 메일 주소와 앱 비밀번호는 Claude Code 사용자 설정 파일에 저장됩니다. PC를 다른 사람과 함께 쓰신다면 주의해 주세요.
- **첨부 파일:** 메일에 들어 있는 파일을 그대로 저장합니다. 한글이 든 CSV가 엑셀에서 깨져 보이면 원본 파일의 문자 인코딩 때문이며, 엑셀의 데이터 → 텍스트/CSV 가져오기에서 UTF-8을 선택하면 열 수 있습니다.
- **메일 내용 속 지시:** 메일 본문에 적힌 지시는 따르지 않도록 Claude에게 안내하고 있습니다. 다만 모르는 사람이 보낸 메일을 다룰 때는 Claude가 실행하려는 작업을 확인해 주세요.
- **예약 작업:** 정해진 시간에 메일을 확인하려면 데스크톱 앱의 예약 작업이나 `/loop`을 사용해 주세요. 클라우드 예약 작업에서는 이 MCP를 사용할 수 없습니다.
## 제거
- Claude Code에게 "korean-mail MCP 지워 줘"라고 요청하시거나 `claude mcp remove korean-mail -s user`를 실행해 주세요. 저장된 메일 주소와 앱 비밀번호도 함께 지워집니다.
- 한 계정만 지우려면 setup에서 **계정 삭제**를 선택해 주세요.
- 네이버·다음에서 만든 앱 비밀번호는 발급한 메뉴에서 직접 폐기해 주세요.
- 내려받은 첨부 파일은 지워지지 않습니다.
## 수동 설치
setup을 쓸 수 없는 경우 아래처럼 직접 등록할 수 있습니다. 같은 서비스의 두 번째 계정부터는 `NAVER_2_EMAIL`, `NAVER_2_APP_PASSWORD`처럼 번호를 붙입니다.
```
# macOS·Linux
claude mcp add --scope user korean-mail -e NAVER_EMAIL=me@naver.com -e NAVER_APP_PASSWORD=앱비밀번호 -- npx -y @cpal1828/korean-mail-mcp
# Windows
claude mcp add --scope user korean-mail -e NAVER_EMAIL=me@naver.com -e NAVER_APP_PASSWORD=앱비밀번호 -- cmd /c npx -y @cpal1828/korean-mail-mcp
```
특정 버전으로 고정하려면 패키지 이름 뒤에 버전을 붙여 주세요(예: `@cpal1828/korean-mail-mcp@0.1.0`).
## 라이선스
MIT
TDQS
Scored across 6 tools
Each tool targets a distinct resource and action: listing folders, listing accounts, searching, reading, downloading attachments, and creating drafts. The only near-overlap (list_folders vs list_accounts) is clearly separated by resource type in the descriptions.
All six tools follow a consistent snake_case verb_noun pattern (list_folders, search_emails, read_email, list_accounts, download_attachment, create_draft). No mixed conventions or vague verbs.
Six tools is well-scoped for a mail client focused on reading and drafting. Each tool earns its place with no redundancy.
The surface covers discovery, search, read, attachment download, and draft creation, but lacks sending, deleting, moving, or marking read/unread. These are notable gaps for a mail domain, though the read-plus-draft scope may be intentional for safety.