naver-works-mcp
Provides tools for interacting with Naver Works email and calendar: listing, searching, reading, sending, forwarding, replying to, and organizing mail (including attachments, folders, and contact lookup), plus creating, updating, searching, and deleting calendar events.
naver-works-mcp (네이버웍스 메일 + 캘린더 통합 MCP)
v2.1 · MIT License · 설치자마다
.env(자격증명)와 서명 파일을 직접 만들어야 합니다.네이버웍스 메일(IMAP/SMTP) + 캘린더(CalDAV)를 외부 앱 비밀번호 하나로 다루는 MCP 서버입니다. 초기 구조는 jaykim81/naver-works-mail-mcp에서 출발했으며, 캘린더·전달·답장 등을 대폭 확장했습니다.
v2.2 변경사항: 임시저장과 본문 검색이 추가됐습니다 (메일 21개, 총 31개).
save_draft(subject, body, to="", cc=None, signature=False)— 발송하지 않고 임시보관함에 저장. 웹/앱에서 열어 수신자·첨부를 보완한 뒤 보낼 때 사용.search_emails_body(query, limit=5, folder="inbox", scan=100)— 본문(+제목) 키워드 검색. 네이버웍스 IMAP은SEARCH TEXT/BODY에 항상 빈 결과를 돌려주므로 최근scan건을BODY.PEEK[]로 내려받아 파이썬에서 대조합니다 (읽음 상태 변경 없음).
v2.1 변경사항: 메일 답장(reply) 기능과 연락처 검색 기능이 새로 추가됐습니다.
reply_email(mail_id, body, folder="inbox", reply_all=False, cc=None, include_attachments=False)추가 — 메일 19개 도구 체제로 확장(총 29개).reply_all=False(기본값)면 원본 발신자에게만,reply_all=True면 원본 To/Cc에 있던 사람들까지 참조로 포함해 전체회신합니다 (내 계정 주소는 자동 제외).cc로 참조자를 추가로 더 넣을 수도 있습니다 (전체회신과 조합 가능).제목은 자동으로
RE: 원본제목으로 붙고(이미RE:면 중복 추가 안 함), 본문은forward_email과 동일한 아웃웍 스타일-----Original Message-----인용 형식과 원본 HTML·인라인 이미지 보존 로직을 그대로 공유합니다 (내부적으로_build_quoted_mime헬퍼로 통합).원본 메일의
Message-ID를 읽어In-Reply-To/References헤더를 채워주므로, 메일 클라이언트에서 실제 답장 스레드로 묶입니다.답장에는 개인 서명이 붙지 않고, 원본 첨부파일은 기본적으로 다시 첨부하지 않습니다 (
include_attachments=True로 켤 수 있음).search_contacts(name, limit=10, scan_per_folder=300)추가 — 네이버웍스 정식 조직도 API 연동(개발자 콘솔 등록 + 관리자 승인 필요) 없이, 받은/보낸메일함 최근 메일들의 From/To/Cc 헤더를 이름으로 뒤져 이메일 주소를 추정합니다. 결과가 여러 건이면 사용자 확인 후 사용을 권장합니다.
v2.0 변경사항: 메일 전달(forward) 기능이 새로 추가됐습니다.
forward_email(mail_id, to, folder="inbox", cc=None, comment="", include_attachments=True)추가 — 메일 17개 도구 체제로 확장(총 27개).제목은 자동으로
FW: 원본제목으로 붙습니다 (이미FW:로 시작하면 중복 추가 안 함).본문은 실제 메일 솔루션(아웃룩 등)이 만드는 전달 인용 형식을 그대로 재현합니다:
-----Original Message----- From: "이름"<이메일> To: <이메일>; Cc: Sent: 2026. 9. 17. (목) 17:18 (GMT+09:00) Subject: 원본 제목From:/To:/Cc:/Sent:/Subject:레이블만 굵게 표시되고,Cc:는 참조자가 없어도 항상 표시됩니다. 날짜는Sent:원본Date헤더를 한국어 아웃룩 스타일로 변환해서 보여줍니다.원본이 HTML 메일이면 plain-text가 아니라 원본 HTML 본문을 그대로 재사용해서 이미지가 포함된 서식이 전달 메일에서도 깨지지 않고 보입니다. 원본에
cid:로 참조하는 인라인 이미지가 있으면Content-ID를 유지한 채 함께 실어 보냅니다(include_attachments로 일반 첨부파일과 함께 껐다 켤 수 있음).전달 메일에는 개인 서명(
signature)이 붙지 않습니다.전달 인용 헤더/코멘트 영역은
Sans Serif폰트로 표시됩니다(원본 본문 자체의 폰트에는 영향 없음).
v1.9 변경사항: send_email 개인 서명(v1.8)의 렌더링 품질 개선.
이메일 클라이언트(특히 Outlook 등 Word 렌더링 엔진 계열)가
<table>에만 지정된font-family를 안쪽<td>/<b>/<span>/<a>까지 상속시키지 않아 기본 대체 폰트로 깨져 보이던 문제를 수정 — 텍스트가 들어가는 요소마다font-family를 각각 명시하도록 변경.서명 폰트 크기 조정: 이름 13px 굵게, 나머지 항목(직책·부서·연락처 등) 12px.
서명 레이아웃 간격 조정: 텍스트 영역과 QR코드 쪽 경계선 사이 간격을 로고↔경계선과 동일한 14px로 맞춤 (경계선↔QR코드 간격은 기존 그대로 유지).
v1.8 변경사항: send_email에 개인 서명 옵션 추가.
send_email(to, subject, body, cc=None, signature=False)—signature=True로 호출하면 본문 끝에 개인 서명(signature.html— 로고·이름/직책/연락처·QR코드 등)을 자동으로 붙여서 보낸다.로고·QR코드는 파일 첨부가 아니라 네이버웍스가 호스팅하는 외부 이미지 URL을
<img src="...">로 그대로 참조하는 방식이라 별도 첨부 파일이 필요 없다.일반 텍스트 클라이언트용 대체 본문(plain 파트)에는 이미지 없이 텍스트 서명만 붙는다.
신규로 작성하는 메일에는
signature=True, 회신/답장/전달에는signature=False(기본값)로 호출하는 것을 권장.
v1.7 변경사항: 메일 발송 줄바꿈 버그 수정.
send_email본문을 HTML로 바꾸는_build_html_body()에서 줄바꿈을"\n"→"<br>\n"로 변환하고 있었는데, 본문 스타일에 걸린white-space:pre-wrap때문에 뒤에 남은 개행문자(\n)까지 실제 줄바꿈으로 한 번 더 렌더링되어 엔터 한 번이 화면에서는 두 번처럼(줄간격이 두 배로) 보이던 문제를 수정했습니다."\n"→"<br>\n"를"\n"→"<br>"로 변경. 문단 사이에 빈 줄을 하나 넣으면 이제 실제로 한 줄만 띄워서 보입니다.
v1.6 변경사항: 폴더 지정이 전면 확장됐습니다.
move_email(mail_id, to_folder, folder)추가 — 메일을 임의의 폴더로 이동합니다. 휴지통에 넣은 메일을 받은편지함으로 되돌릴 때 사용합니다.list_emails/list_unread_emails/search_emails에folder인자 추가 — 이제 휴지통·임시보관함·스팸은 물론 직접 만든 폴더까지 조회·검색할 수 있습니다.폴더 별칭 지원:
inbox/sent/trash/drafts/junk와 한글 이름 (받은편지함,보낸메일함,휴지통,임시보관함,스팸). 그 밖의 값은list_mail_folders()가 알려주는 IMAP 폴더명으로 보고 그대로 사용합니다.기존에는
folder인자가sent가 아니면 무조건 받은편지함으로 처리됐는데, 이제 오타는 조용히 무시되지 않고 해당 폴더를 찾지 못했다는 오류로 드러납니다.
v1.5 변경사항: 메일 정리용 도구 3종이 추가됐습니다.
move_email_to_trash— 메일을 휴지통 폴더로 이동합니다. IMAPMOVE를 먼저 시도하고 서버가 지원하지 않으면COPY+\Deleted플래그 +EXPUNGE로 대체합니다. 휴지통 폴더명은 특수용도 플래그(\Trash)와 이름 힌트로 자동 탐색하며, 실패 시.env의TRASH_FOLDER로 직접 지정할 수 있습니다.delete_local_file—save_attachment로 내려받은 첨부파일을 삭제합니다. 안전장치로ATTACHMENT_DIR또는.env의DELETE_ALLOWED_DIRS아래 파일만 삭제됩니다.list_mail_folders— 서버의 실제 IMAP 폴더 목록을 조회합니다(휴지통 폴더명 확인용).
또한 search_emails / search_sent_emails의 한글 검색 오류를 고쳤습니다. 기존에는
한글 키워드를 넣으면 'ascii' codec can't encode characters 오류가 났는데, CHARSET UTF-8
리터럴 전송 + 실패 시 제목 헤더 직접 대조 폴백으로 동작하도록 바꿨습니다.
v1.4 변경사항: send_email 본문이 맑은 고딕 14px 스타일이 적용된 HTML 메일로
전송되도록 변경했습니다 (일반 텍스트 클라이언트를 위한 대체 텍스트 파트도 함께 포함).
줄바꿈은 그대로 유지되고, 본문에 <, >, & 같은 문자가 있어도 안전하게 이스케이프
처리됩니다.
v1.3 변경사항: send_email에 cc(참조) 파라미터 추가. 메일 목록/상세 조회 결과에도
cc 필드가 추가됩니다. 이와 함께 제목/발신자/수신자 헤더 디코딩 버그도 수정됐습니다 —
기존에는 인코딩된 이름이 여러 개일 때(예: "홍길동 <a@x>, 김철수 <b@x>") 첫 번째 이후가
잘려나갔는데, 전체를 이어붙이도록 고쳤습니다.
v1.2 변경사항: attendees 참석자 초대 기능의 실제 동작이 테스트로 확인됐습니다.
create_my_event/create_team_event에 attendees=["이메일"]을 넘기면 참석자 캘린더에도
일정이 조용히 등록되지만, 초대 알림(수락/거절)은 가지 않습니다. 참석자에게는 별도로
메일/메시지로 알려주는 것을 권장합니다.
Claude 데스크톱에서 네이버웍스 메일(IMAP/SMTP)과 캘린더(CalDAV)를 함께 쓸 수 있는 MCP 서버입니다. 개발자 콘솔 등록이나 관리자 승인 없이, 네이버웍스 외부 앱 비밀번호 하나만으로 동작합니다.
포함 파일
파일 | 설명 |
| MCP 서버 본체 (메일 21개 + 캘린더 10개, 총 31개 도구) |
| 필요 패키지 목록 |
| 자격증명 입력 템플릿 ( |
| 설치 자동화 스크립트 (venv 생성 + 패키지 설치 + |
|
|
|
|
| MIT |
Related MCP server: claude-mail-mcp
제공 도구 (총 31개)
메일 (21개)
도구 | 설명 |
| 받은편지함 최근 메일 조회 |
| 읽지 않은 메일 조회 |
| 특정 발신자 메일 조회 |
| 메일 ID로 전체 내용 조회 |
| 제목 키워드로 검색 |
| 본문(+제목) 키워드로 검색 — 네이버웍스 IMAP이 서버 측 본문 검색(TEXT/BODY)을 지원하지 않아 최근 |
| 보낸메일함 조회/검색 |
| 이름 일부로 이메일 주소 검색 (받은/보낸메일함 From·To·Cc 헤더 기반, 정식 조직도 API 아님, v2.1 신규) |
| 첨부파일 목록/저장/텍스트 추출 |
| 메일을 발송하지 않고 임시보관함에 저장 ( |
| 메일 발송 ( |
| 메일 전달 — 원본 발신자/날짜/제목/수신자를 아웃룩 스타일로 인용, 원본 HTML·인라인 이미지·첨부파일까지 그대로 함께 전달 (v2.0 신규) |
| 메일 답장/전체회신 — |
| 서버의 IMAP 폴더 목록 조회 (휴지통/보낸메일함 실제 폴더명 확인용) |
| 메일을 휴지통 폴더로 이동 ( |
| 메일을 임의 폴더로 이동 — 휴지통 → 받은편지함 복구 포함 |
| 저장된 첨부파일 삭제 (허용 폴더 안에서만 동작) |
캘린더 (10개)
도구 | 설명 |
| 캘린더 목록 |
| 일정 조회 |
| 일정 상세/검색 |
| 일정 등록 (본인/팀 캘린더, |
| 일정 수정/삭제 |
설치 (Windows, PowerShell)
0. 사전 준비
Python 3.10 이상, Git (없으면
winget install -e --id Python.Python.3.12,winget install -e --id Git.Git후 PowerShell을 새로 엽니다)네이버웍스 외부 앱 비밀번호 발급: 네이버웍스 웹 → 프로필 → 개인 설정 → 보안 → 외부 앱 비밀번호 (메일의 IMAP/SMTP, 캘린더 CalDAV 사용이 계정/관리자 설정에서 허용돼 있어야 합니다)
1. 저장소 받기
git clone https://github.com/s4061285-create/naver-works-mcp.git
cd naver-works-mcp2. 설치 — 방법 A — 자동 설치 스크립트 (권장)
.\setup.ps1venv 생성 → 패키지 설치 → .env 파일 준비(메모장 자동 오픈) → 설치 확인까지 한 번에
진행되고, 마지막에 Claude 데스크톱 config에 넣을 JSON을 화면에 출력해줍니다.
PowerShell 실행 정책 때문에 스크립트가 막히면
powershell -ExecutionPolicy Bypass -File .\setup.ps1로 실행하세요.
2. 설치 — 방법 B — 수동 설치
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
copy .env.example .env
notepad .envrequirements.txt에 mcp[cli]<2를 고정해뒀습니다. 그대로 설치하면 mcp 2.x가 잡혀
ModuleNotFoundError: mcp.server.fastmcp 오류가 나므로 반드시 이 버전을 유지하세요.
.env 설정
.env는 배포판에 포함되어 있지 않습니다 (비밀번호가 담기기 때문에 각자 발급받아야
합니다). .env.example을 참고해 아래 값을 채워주세요.
NAVER_EMAIL: 본인 네이버웍스 로그인 이메일NAVER_APP_PASSWORD: 네이버웍스 웹 → 프로필 → 개인 설정 → 보안 → 외부 앱 비밀번호에서 발급받은 값 (로그인 비밀번호 아님, 재확인 불가하니 발급 즉시 복사)NAVER_CALDAV_SERVER: 보통 그대로 둠 (https://caldav.worksmobile.com)ATTACHMENT_DIR: 첨부파일 기본 저장 폴더 (비우면 시스템 임시 폴더)TRASH_FOLDER: 휴지통 폴더명. 비워두면 자동 탐색하며, 자동 탐색이 실패할 때만list_mail_folders()로 확인한 실제 폴더명을 넣어주세요DELETE_ALLOWED_DIRS:delete_local_file이 삭제해도 되는 폴더 (;또는,로 여러 개). 여기에 없는 경로는 삭제 요청이 거부됩니다SIGNATURE_HTML_FILE/SIGNATURE_TEXT_FILE: (선택) 서명 파일 경로. 기본값은 서버 폴더의signature.html/signature.txt
이 비밀번호 하나로 메일과 캘린더가 모두 동작합니다.
서명 설정 (선택)
send_email(signature=True)를 쓰려면 예시 파일을 복사해 본인 정보로 수정합니다.
(signature.html / signature.txt는 .gitignore로 제외되어 커밋되지 않습니다.)
copy signature.example.html signature.html
copy signature.example.txt signature.txt파일이 없는 상태에서 signature=True로 호출하면 안내 오류가 반환됩니다. 로고·QR 이미지는
첨부가 아니라 <img src="https://..."> 외부 URL 참조 방식입니다.
단독 실행 확인
.\.venv\Scripts\python.exe server.py에러 없이 멈춰 있으면 정상입니다 (stdio 대기). Ctrl+C로 종료하세요.
Claude 데스크톱 등록
설정 파일 경로 (일반 설치 버전과 Microsoft Store 버전이 다릅니다):
일반 설치: %APPDATA%\Claude\claude_desktop_config.json
Store 버전: %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.jsonmcpServers에 아래 항목을 추가합니다 (경로는 실제 설치 위치로 교체 — setup.ps1
마지막 출력에 본인 경로가 그대로 나옵니다).
{
"mcpServers": {
"naver-works": {
"command": "<설치 폴더>\\.venv\\Scripts\\python.exe",
"args": ["<설치 폴더>\\server.py"]
}
}
}비밀번호는 .env 파일에서 읽으므로 config에는 넣지 않습니다.
Claude Code를 쓴다면 아래처럼 등록할 수도 있습니다.
claude mcp add naver-works -- "<설치 폴더>\.venv\Scripts\python.exe" "<설치 폴더>\server.py"저장 후 앱을 완전히 종료하고 재시작합니다.
taskkill /IM Claude.exe /F사용 예시
최근 메일 5개 보여줘
안 읽은 메일 있어?
kim@example.com 이 보낸 메일 찾아줘
오늘 일정 알려줘
이번 주 일정 등록해줘: 내일 오후 3시 팀 회의문제 해결
증상 | 원인/조치 |
|
|
| config 경로에 |
401 / 인증 실패 | 로그인 비밀번호를 넣었을 가능성 → 외부 앱 비밀번호로 교체 |
"캘린더를 찾지 못했습니다" | 이메일/비밀번호 오타, 또는 계정에 CalDAV 접근이 막혀 있음 |
Claude에서 도구가 안 보임 | config 경로/JSON 문법 확인, |
로그 파일 위치 (설정 파일과 같은 계층의 logs 폴더):
<설정 파일 경로와 동일한 상위 폴더>\logs\mcp-server-naver-works.log참고
외부 앱 비밀번호는 계정 전체 권한을 가지므로
.env파일에만 두고, 다른 사람과 공유하거나 git에 커밋하지 마세요 (.gitignore에 이미 제외 처리되어 있습니다). 사용 중단 시 네이버웍스 보안 설정에서 폐기하세요.각 PC마다 자기 계정으로 발급받은 외부 앱 비밀번호로
.env를 개별 구성해야 합니다.
라이선스
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
Connect any mailbox to Claude, ChatGPT & AI: read, send, reply, schedule & search emails.
Your mailboxes in ChatGPT and Claude: Gmail, iCloud, Fastmail, any IMAP. Passwords stay yours.
Bring Gmail, Outlook, iCloud Mail, Yahoo Mail, Fastmail and other IMAP mailboxes together. Search connected email, including semantic search; cached or indexed results may be incomplete or stale. Read messages and attachments, create drafts, send or reply when requested, and manage rules for new mail. Separate permissions control reading, attachments, drafts, sending and mailbox changes.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables Claude to read, manage, and send email from any IMAP mailbox over plain IMAP and SMTP, including hosting-company and self-hosted mail servers. It provides tools for searching, reading, moving, deleting, and composing messages while built-in safety rules prevent unintended changes.12MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude to read, search, send, and organize email over IMAP/SMTP and to manage calendars over CalDAV, including finding free slots and creating events, across multiple self-hosted accounts behind one authenticated endpoint.MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to interact with email, contacts, and calendar data through JMAP/CalDAV/WebDAV APIs, including sending, searching, organizing messages, managing contacts, and scheduling events. It also supports attachments, drafts, bulk operations, and installation as a Claude Desktop extension.MIT
- AlicenseAqualityBmaintenanceEnables Claude to connect unlimited Gmail and IMAP mailboxes, search and triage them together while identifying each account, read attachments, and create drafts or perform permitted mailbox actions under configurable safety modes.2355 npm1MIT