Content
# Naver Mail MCP Server for Claude Desktop
Naver Mail MCP Server for Claude Desktop.
## Features
| Tool | Description |
|------|-------------|
| `get_profile` | Get account profile (email, name, total email count, unread count) |
| `search_emails` | Search emails (sender, recipient, subject, date, read status) + pagination |
| `read_email` | Read entire email by UID (header, body, attachment metadata) |
| `read_thread` | Get conversation thread by Message-ID |
| `list_folders` | Get mailbox folder list (message count, unread count) |
| `create_draft` | Save new email draft in Drafts folder |
| `list_drafts` | Get draft list in Drafts folder |
| `send_email` | Send email via SMTP (new email, reply) |
| `download_attachment` | Download attachment (base64 encoding) |
## Installation
```bash
uvx naver-mail-mcp
```
## Claude Desktop Configuration
### After PyPI Distribution (Recommended)
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"naver-email": {
"command": "uvx",
"args": ["naver-mail-mcp"],
"env": {
"NAVER_EMAIL_ADDRESS": "your_email@naver.com",
"NAVER_EMAIL_PASSWORD": "your_app_password",
"NAVER_FULL_NAME": "Your Name"
}
}
}
}
```
### Local Development Mode
Before distributing to PyPI, run directly from local source:
```json
{
"mcpServers": {
"naver-email": {
"command": "/absolute/path/to/uv",
"args": [
"--directory",
"/absolute/path/to/naver-mail-mcp",
"run",
"naver-mail-mcp"
],
"env": {
"NAVER_EMAIL_ADDRESS": "your_email@naver.com",
"NAVER_EMAIL_PASSWORD": "your_app_password",
"NAVER_FULL_NAME": "Your Name"
}
}
}
}
```
> **Note:** Claude Desktop does not inherit system PATH. Use the **absolute path** of `uv` in `command`. (e.g., `/Users/username/.local/bin/uv`)
>
> You can confirm the absolute path with the `which uv` command.
## Prerequisites
1. **Python 3.10+**
2. **Naver account** IMAP/SMTP settings
- Naver Mail → Settings → POP3/IMAP settings → IMAP/SMTP usage ✅
3. **Application password** issuance (2-step verification required)
- Naver → My information → Security settings → 2-step verification → Application password management
## Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `NAVER_EMAIL_ADDRESS` | Yes | Naver email address |
| `NAVER_EMAIL_PASSWORD` | Yes | Application password (not account password) |
| `NAVER_FULL_NAME` | No | Sender display name |
## Tools Reference
### get_profile
Get account profile. No parameters.
### search_emails
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| folder | string | No | INBOX | Folder to search |
| sender | string | No | - | Sender filter |
| recipient | string | No | - | Recipient filter |
| subject | string | No | - | Subject keyword |
| date_from | string | No | - | Start date (DD-Mon-YYYY) |
| date_to | string | No | - | End date (DD-Mon-YYYY) |
| is_read | boolean | No | - | Read status (true/false/null) |
| page | integer | No | 1 | Page number |
| page_size | integer | No | 20 | Results per page (max 100) |
### read_email
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| uid | string | Yes | - | Email unique ID |
| folder | string | No | INBOX | Folder |
### read_thread
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| message_id | string | Yes | - | Message-ID header value |
| folder | string | No | INBOX | Folder |
### list_folders
Get folder list. No parameters.
### create_draft
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| to | array | Yes | - | Recipient list |
| subject | string | Yes | - | Subject |
| body | string | Yes | - | Body |
| body_type | string | No | text/plain | text/plain or text/html |
| cc | array | No | - | CC list |
### list_drafts
Get draft list. No parameters.
### send_email
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| to | array | Yes | - | Recipient list |
| subject | string | Yes | - | Subject |
| body | string | Yes | - | Body |
| body_type | string | No | text/plain | text/plain or text/html |
| cc | array | No | - | CC list |
| in_reply_to | string | No | - | Reply-to Message-ID |
| references | array | No | - | Thread Message-ID list |
### download_attachment
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| uid | string | Yes | - | Email unique ID |
| part_number | string | Yes | - | MIME part number (check with `read_email`) |
| folder | string | No | INBOX | Folder |
## Development
```bash
# Clone and install
git clone https://github.com/chanmuzi/naver-mail-mcp.git
cd naver-mail-mcp
uv venv --python 3.12 .venv
source .venv/bin/activate
uv pip install -e .
# Set credentials
cp .env.example .env
# Edit .env with your credentials
# Run tests
python -m tests.test_integration
```
## Troubleshooting
| Error | Solution |
|-------|----------|
| `IMAP authentication failed` | Check app password. Use application password, not account password |
| `Cannot connect to Naver IMAP server` | Check network, IMAP usage settings |
| `Missing required environment variables` | Set `NAVER_EMAIL_ADDRESS`, `NAVER_EMAIL_PASSWORD` environment variables |
| `Folder not found` | Check available folder names with `list_folders` tool |
| `Failed to spawn process` | Use absolute path of `uv` in `command` (check with `which uv`) |
## Technical Details
- **IMAP**: `imap.naver.com:993` (SSL/TLS)
- **SMTP**: `smtp.naver.com:465` (SSL)
- **Transport**: stdio (Claude Desktop integration)
- **Encoding**: UTF-8, EUC-KR, Modified UTF-7 (folder name) automatic handling
- **Connection**: New connection for each tool call (stateless)
- **Attachment limit**: 10MB (base64 encoding)
## License
MIT
