# 네이버 메일 MCP for Codex

**Codex에서 네이버 메일을 검색하고 읽고, 초안을 만들거나 메일을 보낼 수 있게 연결하는 Windows용 설치 패키지입니다.**

MCP는 AI와 외부 프로그램을 연결하는 규격입니다. 이 프로젝트에서는 Codex가 PC에서 실행되는 Python 프로그램을 통해 네이버 메일에 접속합니다. 별도의 공개 서버나 OpenAI API 키는 필요하지 않습니다.

[chanmuzi/naver-mail-mcp](https://github.com/chanmuzi/naver-mail-mcp)를 바탕으로 Codex 설치 안내, Windows 비밀번호 암호화 저장, 연결 진단 기능을 추가했습니다. 원본 저작권과 MIT 라이선스를 유지합니다. 네이버나 OpenAI가 제공하는 공식 제품은 아닙니다.

## 사용 예시

- “네이버에서 오늘 받은 메일을 요약해줘.”
- “서울시에서 온 메일을 찾아줘.”
- “제목에 견적이 들어간 메일을 검색해줘.”
- “이 메일에 대한 답장 초안을 만들어줘.”

## 지원 기능

| 도구 | 기능 |
|---|---|
| `get_profile` | 계정과 받은편지함 메일 수 확인 |
| `search_emails` | 발신자·제목·날짜·읽음 여부로 검색 |
| `read_email` | 메일 본문과 첨부파일 정보 조회 |
| `read_thread` | 관련 대화 조회 |
| `list_folders` | 메일함 목록 조회 |
| `create_draft` | 초안 저장 |
| `list_drafts` | 초안 목록 조회 |
| `send_email` | 메일 발송 및 답장 |
| `download_attachment` | 첨부파일 가져오기 |

## 준비 사항 — 사용자가 직접 할 일

1. Windows에서 Codex 데스크톱 앱을 설치하고 로그인합니다.
2. [Python](https://www.python.org/downloads/windows/) 3.11 이상을 설치합니다. 설치 시 `Add python.exe to PATH`를 선택합니다.
3. [PowerShell 7](https://learn.microsoft.com/powershell/scripting/install/installing-powershell-on-windows)을 설치합니다. 터미널에서 `pwsh --version`으로 확인할 수 있습니다.
4. 네이버 메일 설정에서 **POP3/IMAP 설정 → IMAP/SMTP 사용**을 켭니다.
5. 네이버 계정의 **보안설정 → 2단계 인증 → 애플리케이션 비밀번호 관리**에서 앱 비밀번호를 발급합니다.

앱 비밀번호는 일반 로그인 비밀번호와 다른 연결 전용 비밀번호입니다. 채팅이나 GitHub에 붙여넣지 마세요.

## 설치 방법

### 1. 다운로드

이 페이지의 **Code → Download ZIP**을 눌러 압축을 풀고, 해당 폴더에서 터미널을 엽니다. Git을 사용한다면:

```powershell
git clone https://github.com/cupid75/naver-mail-mcp-for-codex.git
cd naver-mail-mcp-for-codex
```

### 2. 프로그램 설치

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
```

이 명령은 이 폴더에 전용 Python 실행 환경인 `.venv`를 만들고 필요한 패키지를 설치합니다. 마지막에 도구 9개 조회 테스트가 통과하면 설치 성공입니다. 이 단계에서는 네이버 계정에 로그인하지 않습니다.

`ExecutionPolicy Bypass`는 해당 PowerShell 실행에만 적용되며 시스템 전체 정책을 변경하지 않습니다. 실행 전에 이 저장소의 스크립트를 확인할 수 있습니다.

### 3. 네이버 로그인 설정

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .\setup-credentials.ps1
```

또는 `네이버메일_연결설정.cmd`를 두 번 클릭합니다.

이메일 주소와 앱 비밀번호를 입력합니다. 비밀번호 입력은 화면에 표시되지 않습니다. 실제 MCP 호출로 로그인을 확인하고, 성공한 경우에만 비밀번호를 Windows 계정으로 암호화해 `.local/naver-credential.xml`에 저장합니다.

실패하면 어느 단계에서 실패했는지 표시하고 `.local/connection-status.json`에 진단 결과를 남깁니다. 비밀번호는 진단 메시지에서 가립니다. 기존 암호화 설정이 있었다면 새 로그인 실패 시 기존 파일은 유지됩니다.

### 4. Codex 등록

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .\register-codex.ps1
```

Codex 사용자 설정에 `naver-mail` 서버를 추가합니다. 같은 이름이 이미 있으면 덮어쓰지 않고 중단합니다.

`codex` 명령을 사용할 수 있다면 위의 등록 스크립트를 사용하는 방법을 권장합니다. 앱 메뉴 위치와 관계없이 Codex 사용자 설정에 연결을 추가합니다.

**앱에서 직접 등록하려면 플러그인 메뉴를 확인하세요.** 현재 사용자 화면에서는 플러그인 메뉴로 들어가며, MCP 관리 화면의 위치와 버튼 이름은 앱 버전에 따라 다를 수 있습니다. 아래 값은 **로컬 명령(STDIO)을 입력할 수 있는 MCP 설정 화면**에서 사용합니다. URL만 받는 사용자 지정 MCP 화면은 이 로컬 프로그램의 등록 화면이 아닙니다.

| 항목 | 입력값 |
|---|---|
| 이름 | `naver-mail` |
| 연결 방식 | STDIO / 로컬 명령 |
| 명령 | `pwsh` 또는 `Get-Command pwsh`에서 확인한 전체 경로 |
| 인수 | `-NoLogo -NoProfile -ExecutionPolicy Bypass -File "C:\설치한폴더\start-codex.ps1"` |
| 환경 변수 | 별도 입력 없음 |

공백이 있는 경로는 따옴표로 감싸세요. 인수를 개별 칸에 입력하는 화면이라면 옵션과 값을 각각 입력하며 경로 자체에는 따옴표를 넣지 않습니다.

**로컬 서버 입력 화면을 찾을 수 없거나 `codex` 명령이 없을 때는 설정 파일로 등록할 수 있습니다.**

1. Windows 파일 탐색기의 주소창에 `%USERPROFILE%\.codex`를 입력합니다.
2. `config.toml`을 텍스트 편집기로 엽니다. 수정 전에 복사본을 보관하세요.
3. 기존 내용은 유지하고 아래 항목을 추가합니다. 이미 `[mcp_servers.naver-mail]`이 있으면 같은 항목을 두 번 추가하지 말고 기존 항목을 수정합니다.
4. `command`와 `args`의 경로를 자신의 PC에 맞게 바꾸고 저장합니다.

```toml
[mcp_servers.naver-mail]
command = 'C:\Program Files\PowerShell\7\pwsh.exe'
args = ['-NoLogo', '-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', 'C:\설치한폴더\start-codex.ps1']
```

`command`는 PowerShell에서 `(Get-Command pwsh).Source`로 확인한 경로입니다. 위의 작은따옴표는 TOML 설정 파일에서 Windows 경로를 그대로 쓰기 위한 표기입니다. 비밀번호는 이 파일에 넣지 않습니다.

참고: [OpenAI 공식 MCP 문서](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)에도 사용자 설정 파일을 통한 등록 방법이 안내되어 있습니다. 문서의 “설정 → MCP 서버” 메뉴 설명은 실제 앱의 플러그인 메뉴 배치와 다를 수 있습니다.

### 5. 재시작하고 확인

플러그인 메뉴의 MCP 연결 관리 화면에 재시작 기능이 있으면 실행합니다. 해당 기능을 찾지 못하거나 설정 파일을 직접 수정했다면 Codex 앱을 완전히 종료하고 다시 엽니다. 같은 채팅에서 다음처럼 요청합니다.

> 네이버 메일 MCP의 get_profile로 연결을 확인하고, 최근 메일 3건을 검색해줘.

계정 정보와 검색 결과가 나오면 연결 완료입니다. 설정 파일에 등록됐다는 메시지만으로 실제 연결 성공을 판단하지 마세요.

## 선택: 저장된 설정으로 추가 테스트

```powershell
.\.venv\Scripts\python.exe .\verify_saved_connection.py
```

등록 시 사용하는 실행 파일을 통해 도구 목록, 실제 로그인, 받은편지함 검색, 이미 읽은 메일 한 건의 본문 조회를 확인합니다. 테스트 결과에는 메일 제목이 화면에 나올 수 있지만 본문은 출력하지 않습니다. 이미 읽은 메일이 없으면 본문 테스트를 건너뜁니다. 테스트 과정에서 메일을 보내거나 초안을 만들지 않습니다.

## 보안과 사용 범위

- 비밀번호는 `.env`나 Codex 설정에 평문으로 넣지 않습니다. Windows의 DPAPI 암호화를 사용하며 같은 PC의 같은 Windows 계정에서 복호화합니다. 같은 계정으로 실행되는 프로그램의 접근까지 막는 장치는 아닙니다.
- `.local/`, `.venv/`, `.env` 등은 Git에서 제외합니다. 암호화된 파일도 공개하거나 다른 사람에게 전달하지 마세요.
- 읽기와 첨부파일 조회 시 `BODY.PEEK[]`를 사용해 읽음 상태 변경을 방지합니다.
- 메일 발송 기능도 포함되어 있습니다. Codex의 승인 설정을 확인하고 실제 발송은 수신자와 내용을 확인한 뒤 요청하세요.
- 현재 PC의 로컬 Codex 연결용입니다. ChatGPT 웹과 모바일에서 바로 연결되는 공개 서버를 제공하지 않습니다.
- Python 프로그램과 인터넷 연결이 필요합니다. 프로젝트 폴더를 옮기면 Codex에 등록한 경로도 바꿔야 합니다.
- macOS/Linux에서는 Windows 암호화 설정 스크립트를 사용할 수 없습니다.

## 자주 발생하는 문제

| 증상 | 확인할 것 |
|---|---|
| `FastMCP`를 가져올 수 없음 | MCP 2.x와 원본 코드의 호환 문제입니다. 이 패키지는 검증한 `mcp==1.30.0`을 설치합니다. `install.ps1`을 다시 실행하세요. |
| `IMAP authentication failed` | 이메일 주소, 앱 비밀번호, 네이버 IMAP 설정 확인 |
| `Cannot connect to Naver IMAP server` | 인터넷·방화벽에서 `imap.naver.com:993` 연결 확인 |
| `pwsh` 또는 `python`을 찾지 못함 | 프로그램 설치 후 터미널을 다시 열고 PATH 설정 확인 |
| `codex` 명령을 찾지 못함 | 위의 수동 등록 방법 사용 |
| 등록했는데 도구가 없음 | MCP 서버 또는 Codex 앱 재시작 |
| 암호화 파일을 읽지 못함 | 설정한 Windows 계정과 PC인지 확인하고 로그인 설정 다시 실행 |
| 마지막에 공통 실패 메시지만 나옴 | 실패 단계와 `.local/connection-status.json`을 확인하세요. 공유 전 개인 정보 포함 여부를 확인하세요. |

## 개발 및 검증

```powershell
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe .\check_mcp.py --discovery-only
```

2026-10-16 Windows / Python 3.14 / PowerShell 7 / Codex 환경에서 원본을 기반으로 한 연결의 실제 로그인, 메일 검색, 본문 조회와 Codex 채팅 도구 직접 호출을 확인했습니다. 공개용으로 바꾼 설치 경로와 스크립트는 별도로 점검합니다. 모든 기능과 모든 환경에서의 동작을 보장하는 의미는 아닙니다.

작업 내역은 [CHANGELOG.md](CHANGELOG.md)에 정리했습니다. 개인 메일 내용, 주소, 메일 수, 비밀번호와 대화 원문은 배포 자료에 포함하지 않습니다.

## 출처와 라이선스

- 원본: [chanmuzi/naver-mail-mcp](https://github.com/chanmuzi/naver-mail-mcp)
- 연결 방식: [OpenAI 공식 MCP 안내](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
- 라이선스: [MIT](LICENSE), 원본 저작권자 `chanmuzi`

원본의 IMAP/SMTP 메일 처리 코드를 재사용하며 Codex용 설치·진단·암호화 저장 스크립트와 문서를 추가했습니다.