K-Mail-MCP

Korean Mail MCP Server — 네이버·다음·Gmail·네이트·Yahoo·iCloud를 Claude AI에 연결하는 MCP 플러그인

English summary: K-Mail-MCP is an MCP (Model Context Protocol) server that connects 6 mail services — Naver, Daum/Kakao, Gmail, Nate, Yahoo, and iCloud — to Claude AI. It enables AI-powered email summarization, translation, spam detection, and unified inbox management — all with AES-256-GCM encrypted credentials.

왜 만들었나요?

Gmail은 공식 MCP가 있지만, 한국에서 주로 사용하는 네이버·다음 메일은 아무것도 없었습니다. 메일을 확인하기 위해 여러 메일 서비스에 일일이 로그인하는 건 번거로운 일이라, 한 번에 요약하고 볼 수 있도록 Claude AI와 함께 만들었습니다.

→ 자세한 이야기는 PHILOSOPHY.md를 읽어주세요.

Related MCP server: io.github.p-w-4-z/inbox-mcp

어떻게 사용하나요? — 먼저 이것만 결정하세요

아래 질문 하나에 답하면 필요한 설치 경로가 정해집니다.

"Claude Desktop 앱에서만 쓸 건가요?" → A. 로컬 설치 (가장 쉬움)
"claude.ai 웹/모바일에서도 쓸 건가요?" → B. 원격 서버 설치 (고급)

A. 로컬 설치 (Claude Desktop) — 5분

1단계: 사전 요구사항 확인

• Node.js v20 이상 설치 확인: 터미널에서 node --version 실행

  • v20.x.x 이상이면 통과. 아니면 nodejs.org에서 LTS 버전 설치

• Claude Desktop 설치: claude.ai/download

2단계: 다운로드 및 설치

git clone https://github.com/youngsooco/k-mail-mcp.git
cd k-mail-mcp

또는 Releases에서 ZIP 다운로드 후 압축 해제.

Windows:

install.bat  파일을 더블클릭

macOS/Linux:

chmod +x install.sh && ./install.sh

설치 스크립트가 자동으로 패키지 설치 + Claude Desktop 설정 파일 연결까지 완료합니다.

3단계: 메일 계정 등록

⚠️ 앱 비밀번호가 필요합니다 — 로그인 비밀번호와 다릅니다. 서비스별 발급 방법 섹션을 먼저 확인하세요.

Windows:

setup.bat  파일을 더블클릭

macOS/Linux:

chmod +x setup.sh && ./setup.sh

대화형 메뉴가 열립니다:

============================================
한국 메일 MCP - 계정 설정
============================================
1) 계정 추가 / 수정
2) 계정 목록
3) 계정 삭제
4) AI 스팸 필터 설정 (Claude Haiku API 키) (미등록)
5) 종료

1을 선택 → 서비스·이메일·앱 비밀번호·별칭 입력. 입력값은 AES-256-GCM으로 암호화되어 저장됩니다.

4단계: Claude Desktop 재시작

Claude Desktop을 트레이에서 완전히 종료 후 다시 실행. 좌측 도구 메뉴에서 k-mail-mcp가 보이면 완료입니다.

이제 Claude에서 말을 걸어보세요:

"새 메일 확인해줘"
"오늘 받은 메일 요약해줘"
"영문 메일 번역해줘"

서비스별 앱 비밀번호 발급 방법

앱 비밀번호 = IMAP 전용 별도 비밀번호. 로그인 비밀번호로는 연결이 거부됩니다.

네이버 메일

1. 네이버 보안설정 접속

2. 2단계 인증 → 활성화 (미활성 시 앱 비밀번호 발급 불가)

3. 애플리케이션 비밀번호 → 추가 → 이름 입력 (예: Claude) → 발급

4. 생성된 비밀번호 복사 ← 창 닫으면 다시 볼 수 없음

5. 네이버 메일 → 환경설정 → IMAP/SMTP 설정 → 사용함 체크

6. setup.bat 실행 → 네이버 계정 등록 시 복사한 비밀번호 입력

다음/카카오 메일

1. 다음 메일 → 설정 → IMAP/POP3 탭

2. IMAP 사용 → 사용함 선택

3. [비밀번호 확인하기] 클릭 → 카카오 인증 → 표시된 비밀번호 복사

4. setup.bat 실행 → 다음 계정 등록 시 복사한 비밀번호 입력

다음은 별도 발급이 아니라, 위 화면에서 이미 생성된 전용 비밀번호를 확인하는 방식입니다.

Gmail

1. Google 계정 → 보안 탭

2. 2단계 인증 활성화 (미활성 시 앱 비밀번호 발급 불가)

3. 검색창에 앱 비밀번호 검색 → 클릭

4. 앱 이름 입력 (예: Claude) → 만들기

5. 생성된 16자리 비밀번호 복사 ← 창 닫으면 다시 볼 수 없음

6. setup.bat 실행 → Gmail 계정 등록 시 복사한 비밀번호 입력

네이트

1. 네이트 메일 → 설정 → 외부 메일 앱 연결

2. IMAP 사용 → 활성화

3. 2단계 인증 미사용 시 로그인 비밀번호 그대로 사용 가능

4. 2단계 인증 사용 중이면 보안 설정에서 앱 비밀번호 발급

⚠️ 미검증 서비스: 충분히 테스트되지 않았습니다.

Yahoo

1. Yahoo 계정 보안 접속

2. 앱 비밀번호 생성 → 앱 이름 입력 → 16자리 비밀번호 복사

3. setup.bat 실행 → Yahoo 계정 등록 시 복사한 비밀번호 입력

⚠️ 미검증 서비스: 충분히 테스트되지 않았습니다.

iCloud

1. Apple ID → 로그인 및 보안

2. 앱 전용 암호 → 암호 생성 → 이름 입력 → 비밀번호 복사

3. setup.bat 실행 → iCloud 계정 등록 시 복사한 비밀번호 입력

iCloud는 2단계 인증이 항상 켜져 있어 앱 전용 암호가 필수입니다. ⚠️ 미검증 서비스: 충분히 테스트되지 않았습니다.

B. 원격 서버 설치 (claude.ai 웹/앱)

이 섹션은 claude.ai 웹 또는 모바일 앱에서 직접 K-Mail-MCP를 사용하고 싶을 때만 필요합니다. Claude Desktop만 사용한다면 위의 A 섹션만으로 충분합니다.

작동 방식

claude.ai (Anthropic 클라우드)
    ↓ 자동 탐색: GET /.well-known/oauth-authorization-server
    ↓ 자동 등록: POST /register
    ↓ 사용자 브라우저: GET /authorize → API 키 입력 페이지
    ↓ 인증 완료: POST /token → access token 발급
    ↓ MCP 연결: POST /mcp + Bearer token
내 서버 (공인 IP 또는 Tunnel)

사전 요구사항

• 외부에서 접근 가능한 서버 (공인 IP, Cloudflare Tunnel, Tailscale Funnel 등)

• Node.js v20+

• MCP_API_KEY 환경변수 (이 값이 OAuth 로그인 비밀번호)

서버 시작

export MAIL_MCP_HTTP_PORT=8766
export MCP_API_KEY="원하는-비밀키"                 # 로그인 시 입력할 값
export MAIL_MCP_BASE_URL="https://your-domain.com"  # 외부 접근 가능한 URL (/ 없이)

node index.js

정상 시작 로그:

[k-mail-mcp] v1.4.5 OAuth2 MCP 서버 시작 — port 8766
  issuer:   https://your-domain.com
  MCP:      https://your-domain.com/mcp
  metadata: https://your-domain.com/.well-known/oauth-authorization-server

Cloudflare Tunnel로 외부 노출 (고정 IP 없을 때)

# cloudflared 설치: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/

# 임시 터널 (URL 매번 변경)
cloudflared tunnel --url http://localhost:8766

# 출력된 URL을 MAIL_MCP_BASE_URL에 사용

CF Tunnel 무료 플랜은 커스텀 도메인 없이도 사용 가능합니다. 단, 랜덤 URL이 재시작마다 변경됩니다. 고정 URL이 필요하면 Cloudflare 계정 연결 후 커스텀 도메인을 설정하세요.

claude.ai에서 연결하기

1. claude.ai → 설정(Settings) → 연결(Connections)

2. MCP 서버 추가(Add MCP Server) 클릭

3. 입력:

4. 저장 → 연결 클릭

5. 브라우저에 로그인 페이지 표시 → MCP_API_KEY 값 입력 → 연결 허용

6. 완료 — claude.ai에서 k-mail-mcp 툴 사용 가능

토큰 유효 기간

• 액세스 토큰: 30일 (재로그인 불필요)

• 서버 재시작 시 모든 토큰 초기화 → 재로그인 필요

• 만료 시 claude.ai가 자동으로 재인증 페이지 표시

주요 기능

• 멀티 계정 통합 — 네이버, 다음/카카오, Gmail 계정을 하나의 MCP로 연결

• 전체 폴더 순회 — INBOX뿐 아니라 모든 IMAP 폴더를 자동 발견하여 순회

• 증분 수집 — 마지막 확인 이후 읽지 않은 메일만 가져옴

• AI 자동 분류 — 맞춤형 카테고리로 자동 분류 (categories.json으로 커스터마이징)

• 카테고리 자동 생성 — 실제 메일 패턴을 AI가 분석해 나만의 카테고리 규칙 생성

• 영문 메일 번역 — 영문 메일 자동 감지 후 Claude가 한국어로 번역·요약

• 메일 링크 — Gmail은 해당 메일 딥링크, 네이버·다음은 받은편지함 링크 제공

• 완전 암호화 — 이메일 주소 + 비밀번호 + API 키 모두 AES-256-GCM 암호화 저장

• 인스턴스 격리 — 설치본마다 고유 키 생성, 다른 PC와 데이터 공유 불가

• OAuth 2.0 원격 접속 — claude.ai custom connector로 원격 연결 (v1.4.0+)

사용 방법

Claude에서 자연어로 말하면 됩니다:

"새 메일 확인해줘"
"오늘 받은 메일 카테고리별로 정리해줘"
"영문 메일만 번역해서 요약해줘"
"다음 계정에서 읽지 않은 메일 보여줘"
"AI 관련 메일만 찾아줘"
"저번에 확인한 이후로 새 메일 있어?"
"내 메일 패턴 보고 카테고리 자동으로 만들어줘"
"어떤 폴더들을 스캔하고 있어?"
"카페편지함은 스캔에서 빼줘"

MCP Tool 목록

지원 메일 서비스

⚠️ 미검증 서비스 사용자 분들께: 동작 여부(성공·실패·오류 메시지)를 GitHub Issues에 알려주시면 빠르게 반영하겠습니다.

지원하지 않는 서비스

IMAP 설정을 아는 경우 index.js의 PRESETS 객체에 직접 추가 가능합니다. CONTRIBUTING.md 참고

지원 플랫폼

⚠️ macOS / Linux 사용자 분들께: install.sh / setup.sh는 충분히 검증되지 않았습니다. 동작 여부를 GitHub Issues에 알려주시면 빠르게 반영하겠습니다.

카테고리 커스터마이징

방법 1: AI 자동 생성 (권장)

Claude: "내 메일 패턴 보고 카테고리 자동으로 만들어줘"
→ generate_categories 툴 실행
→ 미리보기 확인 후 "저장해줘" 요청

방법 2: 직접 편집

categories.json 파일을 수정하면 됩니다 (Claude Desktop 재시작 불필요):

[
  {
    "name": "🏥 의료/헬스케어",
    "keywords": ["병원", "처방", "진료", "약국", "건강검진", "clinic", "hospital"]
  },
  {
    "name": "📚 교육/학습",
    "keywords": ["강의", "수강", "coursera", "udemy", "인프런", "수료"]
  }
]

• name: 이모지 + 카테고리명

• keywords: from(발신자) + subject(제목)에서 검색할 키워드 (대소문자 무시)

• newsletterOnly: true이면 List-Unsubscribe 헤더 있는 메일에만 적용

• categories.json 없거나 비어있으면 기본 9개 카테고리 자동 사용

스팸 탐지 — 4단계 필터링

1~3단계는 별도 설정 없이 자동 동작. 4단계는 setup.bat → 4번 메뉴로 API 키 등록 시 활성화.

spamScore = 패턴점수 + DNSBL점수 + 인증점수(SPF/DKIM/DMARC) ± AI조정
isSpam = spamScore >= 70

데이터 흐름 및 보안

사용자 입력 (setup.bat / setup.sh)
├─ 이메일 주소 + 앱 비밀번호
│   ↓ AES-256-GCM 암호화
│   accounts.enc.json
│
└─ Anthropic API 키 (선택)
    ↓ AES-256-GCM 암호화
    settings.enc.json

.master.key ← 이 설치본 전용 256-bit 키 (자동 생성)
    ↓
MCP 서버 실행 시 → 메모리에서만 복호화 → IMAP 연결 / Haiku API 호출
    ↓
서버 종료 → 평문 완전 소멸

• 비밀번호·API 키는 파일에 절대 평문으로 저장되지 않습니다

• .master.key는 이 PC에만 존재합니다

• Claude (Anthropic) 서버로 비밀번호가 전송되지 않습니다

OAuth 2.0 보안 설계 (v1.4.0+)

보안 패치 이력

자주 묻는 질문

Claude Desktop (로컬 모드)

Q. setup.bat을 실행했는데 아무것도 안 뜹니다. A. node --version으로 Node.js 버전 확인. v20 미만이면 nodejs.org에서 LTS 설치 후 install.bat 먼저 실행.

Q. Claude Desktop에서 k-mail-mcp가 보이지 않습니다. A. install.bat 재실행 → Claude Desktop 트레이에서 완전 종료 → 재시작.

Q. Claude Desktop 업데이트 후 MCP가 사라졌습니다. A. install.bat을 다시 실행하세요.

Q. claude_desktop_config.json 파일이 어디 있나요? A. Windows 탐색기 주소창에 %APPDATA%\Claude 입력.

Q. 네이버 IMAP 연결 오류가 납니다. A. ① 2단계 인증 활성화 ② 앱 비밀번호 재발급 ③ 네이버 메일 → IMAP/SMTP 설정 → 사용 켜기

Q. 다음 메일 연결이 안 됩니다. A. 다음 메일 웹 → 환경설정 → 외부 메일 앱 연결 → IMAP 사용 켜기.

claude.ai 원격 MCP (OAuth 모드)

Q. "MCP 서버를 찾을 수 없습니다" 오류가 납니다. A. 브라우저에서 https://your-domain.com/.well-known/oauth-authorization-server를 직접 열어 JSON이 반환되는지 확인.

Q. OAuth 클라이언트 ID / 시크릿에 뭘 입력해야 하나요? A. 비워두세요. 동적 클라이언트 등록(RFC 7591)으로 자동 처리됩니다.

Q. 서버 재시작 후 다시 로그인하라고 합니다. A. 정상입니다. 토큰이 인메모리에만 저장되므로 재시작 시 초기화됩니다.

Q. API 키는 무엇인가요? A. MCP_API_KEY 환경변수로 설정한 값입니다. OAuth 로그인 페이지에서 이 값을 입력합니다.

공통

Q. .master.key를 실수로 삭제했습니다. A. 복구 불가. accounts.enc.json, .instance.json 삭제 후 setup.bat으로 계정 재등록.

Q. 여러 PC에서 같은 계정을 쓰고 싶습니다. A. 각 PC에서 독립적으로 setup.bat 실행. .master.key는 복사하지 마세요.

Q. iOS/Android에서 사용할 수 있나요? A. 현재 Claude 앱은 MCP를 지원하지 않아 불가합니다.

Q. 다른 메일 서비스를 추가할 수 있나요? A. IMAP을 지원하는 모든 서비스는 index.js의 PRESETS 객체에 추가 가능. CONTRIBUTING.md 참고.

Q. watched_mailboxes.json이 git에 올라갑니다. A. v1.3.0부터 .gitignore에 자동 포함. 이미 올라간 경우: git rm --cached watched_mailboxes.json.

파일 구조

k-mail-mcp/
├── index.js             MCP 서버 본체 — stdio / HTTP+OAuth2 듀얼 모드
├── oauth.js             OAuth 2.0 Provider
├── categories.json      카테고리 규칙 (사용자 정의 가능)
├── install.bat          Windows 설치 (더블클릭)
├── install.ps1          설치 로직 (PowerShell)
├── install.sh           macOS/Linux 설치
├── setup.bat            Windows 계정·설정 관리 (더블클릭)
├── setup.ps1            계정·설정 관리 UI (PowerShell)
├── setup.sh             macOS/Linux 계정·설정 관리
├── setup-worker.js      암호화/저장 코어
├── package.json
├── INSTALL_GUIDE.md     플랫폼별 상세 설치 가이드
├── CONTRIBUTING.md
├── PHILOSOPHY.md
└── ROADMAP.md

자동 생성 파일 (공유 금지):

accounts.enc.json        계정 정보 (AES-256-GCM 암호화)
settings.enc.json        API 키 등 설정 (AES-256-GCM 암호화)
.master.key              256-bit 암호화 키 (절대 공유·백업 금지)
.instance.json           인스턴스 식별자
last_run.json            마지막 실행 시각
watched_mailboxes.json   폴더 발견 캐시 (이 PC 전용)

AI와 함께 만들고 유지합니다

이 프로젝트는 Claude AI (Anthropic)와 함께 설계·개발·문서화됐습니다.

GitHub에서 이슈를 등록하거나 PR을 올리면 Claude AI가 자동으로 검토·답변합니다. 최종 결정은 항상 사람(메인테이너)이 합니다.

기여자

• dadfkim — dadfkim@hanmail.net · GitHub · LinkedIn

• Claude Sonnet (Anthropic) — AI 공동 개발자 · 자동화 유지보수

기여를 원하시면 CONTRIBUTING.md를 읽어주세요.

라이선스

MIT License © 2026 dadfkim