Skip to main content
Glama
korean-mail-mcp

korean-mail-mcp

by cpa333
README.md
# 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

A3.8/5.0

Scored across 6 tools

Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

Six tools is well-scoped for a mail client focused on reading and drafting. Each tool earns its place with no redundancy.

Completeness3/5

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.