Yahoo Mail MCP Server

Yahoo Mail의 완전한 이메일 관리를 IMAP을 통해 제공하는 Model Context Protocol(MCP) 서버입니다. 이 서버는 로컬 stdio 전송(Claude Desktop용)과 HTTP/SSE 전송(Claude.ai를 통한 원격 접속용)을 모두 지원합니다.

기능

• 안전한 OAuth 2.0 인증: PKCE가 포함된 OAuth 2.0 인가 코드 흐름으로 원격 MCP 서버를 보호합니다

• UID 기반 작업: 이메일 삭제 시에도 변하지 않는 영구 IMAP UID를 사용합니다(v3.0.0+)

• 전체 메일 관리: 일괄 처리 지원이 포함된 완전한 이메일 작업

• 11가지 강력한 도구:

  • list_emails: 확장 메타데이터(크기, 플래그, 첨부파일)와 페이지네이션을 포함한 최근 이메일 목록

  • read_email: 이메일 전체 내용 읽기(일괄 지원)

  • search_emails: 필터(날짜 범위, 발신자, 안 읽음 상태)를 사용한 고급 검색

  • list_folders: 사용 가능한 모든 IMAP 폴더를 발견

  • delete_emails: 이메일을 휴지통으로 이동(소프트 삭제, 복구 가능)

  • archive_emails: 장기 보관을 위해 이메일을 보관

  • mark_as_read: 이메일을 읽음으로 표시

  • mark_as_unread: 이메일을 안 읽음으로 표시

  • flag_emails: 이메일을 중요/별표로 표시

  • unflag_emails: 이메일의 플래그(중요 표시)를 제거

  • move_emails: 이메일을 다른 폴더로 이동

• Enrich:기 : 모든 이메일에는 UID, 크기(size), 플래그(flag), hasAttachments 및 폴더 정보가 포함됩니다.

• 고급 검색: 날짜, 발신자, 안 읽음 상테 필터 등과 함께 및 모든 폴더에서 검색 가능

• 두 전송 모속: 모든 관리 조작은 동시에 여러 이메일을 처리할 수 있으며 성공/실패를 정확하게 추적합니다

• 두 가지 전송 모드:

  • stdio: 로컬 Claude Desktop 통합용

  • sse: HTTP/Server-Sent Events를 통한 원격 접속용(Render.com에 필수)

• 크로스플랫폼: Windows 및 Linux 개발 환경에서 모두 사용 가능

• Docker 지원: Docker 및 Docker Compose를 사용한 컨테이너 배포

• 클라우드 지원 대비: OAuth 보안을 갖춘 Render.com에 쉽게 배포할 수 있습니다

Related MCP server: Yahoo Mail MCP Server

사전 준비

로컬 개발

• Node.js: 18.0.0 이상

• Yahoo 메일 계정: 앱 비밀번호를 사용할 수 있는 계정

• Git: 버전 관리 도구

Docker 개발/배포

• Docker: 최신 버전

• Docker Compose: 최신 버전 (Windows/Mac으 Docker Desktop에 함된)

Render.com 배포용

• GitHub 계정: 저장소 호스팅 용도

• Render.com: https://your-host에서 미정 부하 이용 가능

신속한 시작

1. 저장소 준Clone and Setup

# Clone the repository
git clone <your-repo-url>
cd yahoo-mail-mcp-server

# Copy environment template
cp .env.example .env

2. Yahoo 메일 비밀번호 가져오기

1. https://login.yahoo.com/account/security로 이동

2. "앱 비밀번호 생성(Generate app password)"을 클릭하거나, "앱 비밀번호 관리(Manage app passwords)"를 클릭

3. "기타 앱(Other App)"➡을 선택하고 "MCP Server""를 입

4. 생성된 16자리 비밀번호를 복사한다

4. 환경 구성

.env 파일에 자격 증명을 입력하세요:

YAHOO_EMAIL=your.email@yahoo.com
YAHOO_APP_PASSWORD=your16charpassword
TRANSPORT_MODE=stdio  # or 'sse' for HTTP mode
PORT=3000

종속성 설치

Windows (PowerShell):

npm install

Linux/macOS (Bash):

npm install

로컬 실행

stdio 모드[긴 시 mode for Claude Desktop]:

npm run start:stdio

SSE 모드[:]

npm run start:sse

Development 모드(자동 리로드):

npm run dev

Docker 사용

Docker로 빌드 및 실 실행

클라이언트:

# Build the image
npm run docker:build

# Run the container
npm run docker:run

# Or use Docker Compose (recommended)
npm run docker:compose:up

# View logs
npm run docker:compose:logs

# Stop containers
npm run docker:compose:down

클라이언트:

# Build the image
npm run docker:build

# Run the container
npm run docker:run

# Or use Docker Compose (recommended)
npm run docker:compose:up

# View logs
npm run docker:compose:logs

# Stop containers
npm run docker:compose:down

Docker 명령어로 실행

Windows (PowerShell):

# Build
docker build -t yahoo-mail-mcp .

# Run
docker run -p 3000:3000 `
  -e YAHOO_EMAIL=your.email@yahoo.com `
  -e YAHOO_APP_PASSWORD=yourpassword `
  -e TRANSPORT_MODE=sse `
  yahoo-mail-mcp

# Or with Docker Compose
docker-compose up -d

Linux/macOS (Bash):

# Build
docker build -t yahoo-mail-mcp .

# Run
docker run -p 3000:3000 \
  -e YAHOO_EMAIL=your.email@yahoo.com \
  -e YAHOO_APP_PASSWORD=yourpassword \
  -e TRANSPORT_MODE=sse \
  yahoo-mail-mcp

# Or with Docker Compose
docker-compose up -d

서버 테스트

Health 엔드포인트 테스트

Windows (PowerShell):

# Using npm script
npm run test:health

# Using curl (if installed)
curl http://localhost:3000/health

# Using PowerShell
Invoke-WebRequest -Uri http://localhost:3000/health | Select-Object -Expand Content

Linux/macOS (Bash):

# Using npm script
npm run test:health

# Using curl
curl http://localhost:3000/health

SSE 엔드포인트 테스트

Windows (PowerShell):

# Using npm script
npm run test:sse

# Using curl
curl http://localhost:3000/mcp/sse

# Using PowerShell
Invoke-WebRequest -Uri http://localhost:3000/mcp/sse

Linux/macOS (Bash):

# Using npm script
npm run test:sse

# Using curl
curl http://localhost:3000/mcp/sse

Render.com에 배포

단계1: 저장소 준비

Windows (PowerShell):

# Initialize git (if not already done)
git init

# Add all files
git add .

# Commit
git commit -m "Initial commit: Yahoo Mail MCP Server"

# Create GitHub repository at https://github.com/new
# Then push to GitHub
git remote add origin https://github.com/yourusername/yahoo-mail-mcp-server.git
git branch -M main
git push -u origin main

Linux/macOS (Bash):

# Initialize git (if not already done)
git init

# Add all files
git add .

# Commit
git commit -m "Initial commit: Yahoo Mail MCP Server"

# Create GitHub repository at https://github.com/new
# Then push to GitHub
git remote add origin https://github.com/yourusername/yahoo-mail-mcp-server.git
git branch -M main
git push -u origin main

단계2: Render에 배포

1. Render.com에 가입/로그인

   • https://render.com으로 이동

   • "무효로 시직(Get Started for Free)" 또는 "로그인" 클릭

2. GitHub 저장소 연결

   • 오른쪽 위 여에 "New +" 버튼을 클릭

   • "Web Service"를 선택

   • "Connect GitHub"을 눌러 Render에게 인증을 허가하고

   • yahoo-mail-mcp-server 저장소를 선택

3. 서비스 구성

   • Name: yahoo-mail-mcp-server (또는 다른 선호하는 이름)

   • Runtime: Docker

   • Region: 가청 가까운 지역을 선택하세요 (Oregon, Frr..- German, Singur, Ohio)

   • Branch: main

   • Plan: Free (또는 프로덕션에는 Starter 권장)

4. 환경 변수 설속

   "환경" 섹션에서 "환경 변수 추개(Add Environment Variable)"를 클릭하고 다음을 추가하세요:

   키	값	생성 방법
   NODE_ENV	production	-
   TRANSPORT_MODE	sse	-
   YAHOO_EMAIL	your.email@yaho.com	사용자의 Yahoo 메일 이메일
   YAHOO_APP_PASSWORD	your16charpassword	"Yahoo 메일 앱passWord 보기" 섹션을 참조하세요
   OAUTH_CLIENT_ID	32-char-hex-string	를 실행: openssl rand -hex 16
   OAUTH_CLIENT_SECRET	64-char-hex-string	실행: openssl rand -hex 32

   주요 사항:

   • YAHOO_EMAIL, YAHOO_APP_PASSWORD, OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET을 "Secret" 비밀 값으로 표시하세요

   • PORT는 Render가 자동으로 설정하므로, 직접 추가하지 마세요

   • OAuth 자격 증명을 저장해두세요 - Claude Desktop 설정 시 필요합니다

5. 배포

   • "Create Web Service"를 클릭

   • Render가 당신의 Docker 컨테이너를 자동으로 빌드 및 배포합니다.

   • 배포가 완료될 때까지 기다리세요 (최초 빌드는 5~10분 소요)

6. 서비스 URL 획득

   • 데포이 완왼되면, https://yahoo-mail-mcp-server.onrender.com 같은 형태의 URL이 제공됩니다

   • 확인: https://yahoo-mail-mcp-server.onrender.com/health에 접속해 테스트하세요

3단계: Claude Desktop에 연결

Note: 원격 MCP 서버를 이용하려면 Claude Pro, Max, Team 또는 Enterprise 플랜이 필요합니다.

1. Claude Desktop 열기

   • 컴퓨터에서 Claude Desktop 앱을 실행합니다.

2. MCP 커넥터 추가

   • 사용자 아이콘 또는 메뉴를 클릭

   • "Settings" 선택

   • "Connectors" 섹션으로 이동

   • "Add Custom Connector"을 클릭합니다

3. 커넥터 구성

   • Name: Yahoo Mail

   • URL: https://your-service-name.onrender.com/mcp/sse

   예를 들면:

   https://yahoo-mail-mcp-server.onrender.com/mcp/sse

4. OAuth 인증 설정

   • "Advanced Settings(고급 설정)" ⚙️ 클릭

   • 4단계에서 발급된 OAuth 자격 증명을 입력하세요:

     • OAuth Client ID: OAUTH_CLIENT_ID 환경 변수의 값

     • OAuth Client Secret: OAUTH_CLIENT_SECRET 환경 변수의 값

5. 저장 및 테스트

   • "Add" 또는 "Save"을 클릭

   • Claude Desktop이 OAuth 2.0을 사용하여 인증합니다

   • 성공적으로 완료되면 커넥터가 활성 상태로 표시됩니다

   • 이제 대화에서 Yahoo Mail의 도구를 사용할 수 있습니다.

4단계: Claude.ai에서 MCP 서버 사용

연결에 성공하면 대화에서 다음의 도구를 사용할 수 있습니다:

Can you list my recent emails?

Can you read email number 5?

Can you search for emails from john@example.com?

문제 해결

일반적인 문제

1. "Authentication failed(인증 실패)" 오류

해결 방법: 앱 전용 비밀번호를 확인하세요

• 사용 중인 것이 일반 Yahoo 비밀번호가 아니라 앱 전용 비밀번호인지 확인

• https://login.yahoo.com/account/security에서 새 앱 전용 비밀번호를 생성

• 마침표 및 오타가 .env 파일이나 Render 환경 변수에 없는지 확인

2. Windows에서 Docker 빌드가 실패하는 경우

해결 방법: Docker Desktop 설정 확인

• Docker Desktop이 실행 중인지 확인

• WSL2 기반 엔진 사용 여부 확인 (Settings > General > Use SWH2 based enngine)

• 파일 공유가 설정되어 있는지 확인 (Settings > Resources > File Sharing)

3. 포트 3000 이미 사용 중

해결 방법: 포트 번호를 변경하세요

Windows (PowerShell):

$env:PORT=3001; npm run start:sse

Linux/macOS (Bash):

PORT=3001 npm run start:sse

또는 .env 편집:

PORT=3001

4. Render 배포 실패

해결 방법: 로그를 확인하세요

• Render 대시보드로 이동

• 서비스(Service) 선택

• "Logs" 탭 클릭

• 오류 메시지가 있는지 확인

• 일반적인 상황:

  • 필수 환경 변수가 설정되지 않았을 경우

  • Dockerfile 경로가 정확하지 않은 경우

  • 빌드 시간 초과 (설정에서 빌드 시간 초과 설정을 늘리세요)

5. SSE 연결 끊김

해결 방법: 무료 요금제의 제한 사항

• 일반 등급 서비스는 활동이 15분 없을 때 절전 모드로 전환됩니다.

• 일시정지 후의 첫 번째 요청은 응답 시간에 30~60초 걸릴 수 있습니다.

• 항상 유지가 필요하다면 Starter 플랜($7/월)으로 업그레이드하세요.

6. IMAP 연결 시간 초과

해결 방법: Yahoo Mail IMAP 설정 확인

• Yahoo Mail 설정에서 IMAP이 활성화되어 있는지 확인

• Yahoo Mail > 설정 > 더 많은 설정 > 사서함으로 이동

• 방화벽이 포트 993을 차단하고 있지 않은지 확인

Windows에서 발생하는 문제

줄 바꿈 문제

줄 바꿈 문제와 관련된 오류가 표시된다면:

PowerShell:

# Configure git to handle line endings correctly
git config --global core.autocrlf input

# Re-clone the repository
git clone <your-repo-url>

npm 스크립트 오류가 나는 경우

크로스플랫폼 스크립트가 실행되지 않을 때:

PowerShell:

# Install cross-env globally
npm install -g cross-env

# Or run scripts directly
node server.js

Linux 전용 문제

Docker 관련 권한 오류

Bash:

# Add user to docker group
sudo usermod -aG docker $USER

# Logout and login again, or run:
newgrp docker

# Test
docker ps

환경 변수 참조

Note: OAUTH_CLIENT_ID와 OAUTH_CLIENT_SECRET는 원격 배포(Render.com)에서만 필요합니다. 로컬 stdio 모든에서 OAuth는 필수가 아닙니다.

사용 가능한 npm 스크립트

Project Structure

yahoo-mail-mcp-server/
├── server.js                 # Main server code
├── package.json             # Node.js dependencies and scripts
├── Dockerfile               # Docker build configuration
├── docker-compose.yml       # Docker Compose configuration
├── render.yaml              # Render.com deployment config
├── .env.example             # Environment variable template
├── .env                     # Your local environment variables (gitignored)
├── .dockerignore            # Files to exclude from Docker build
├── .gitignore               # Files to exclude from git
├── .gitattributes           # Git line ending configuration
└── README.md                # This file

Security Best Practices

1. OAuth 2.0 보호 (원격 배포)

   • 모든 MCP 요청에 대해 서버가 OAuth 2.0 인증을 요구합니다

   • PKCE(코드 교환 증명 키, Proof Key for Code Exchange)가 포함된 인증 코드 흐름을 사용합니다

   • 올바른 자격 증명을 가진 클라이언트만 이메일에 접근할 수 있습니다

   • 강력한 임의 자격 증명 생성: openssl rand -hex 16 및 openssl rand -hex 32

   • 자격 증명을 Render 대시보드에 안전하게 저장합니다("Secret"으로 표시)

2. 자격 증명을 커밋하지 마세요

   • .env 파일은 gitignore 처리됩니다

   • 항상 .env.example을 템플릿으로 사용하세요

   • 민감한 값은 Render 대시보드에서 설정하세요

   • OAuth 자격 증명을 공개적으로 공유하지 마세요

3. 앱별 비밀번호를 사용하세요

   • 기본 Yahoo 비밀번호는 절대 사용하지 마세요

   • 각 서비스마다 새 비밀번호를 생성하세요

   • 사용하지 않는 비밀번호는 정기적으로 해지하세요

   • 앱 비밀번호는 기본 비밀번호를 변경하지 않고도 해지할 수 있습니다

4. 이메일 관리 작업

   • 모든 수정 작업은 되돌릴 수 있습니다(소프트 삭제, 영구 삭제 아님)

   • 삭제된 이메일은 휴지통 폴더로 이동합니다(무료 계정은 7일 이내 복구 가능)

   • 보관, 깃발, 읽음 상태 변경은 데이터를 손상시키지 않습니다

   • 이동 작업은 이메일 내용과 메타데이터를 보존합니다

   • 발신 작업 없음 - 서버는 사용자를 대신하여 이메일을 보낼 수 없습니다

5. 프로덕션 환경에서 HTTPS 사용

   • Render.com은 무료 SSL 인증서를 제공합니다

   • 모든 트래픽은 암호화됩니다(TLS/SSL)

   • IMAP 연결은 TLS를 사용합니다

   • OAuth 토큰은 안전하게 전송됩니다

개발 워크플로우

변경 사항 만들기

Windows (PowerShell):

# 1. Make your changes to server.js

# 2. Test locally
npm run dev

# 3. Test with Docker
npm run docker:compose:up

# 4. Commit and push
git add .
git commit -m "Description of changes"
git push origin main

# 5. Render automatically deploys the changes

Linux/MacOS (Bash):

# 1. Make your changes to server.js

# 2. Test locally
npm run dev

# 3. Test with Docker
npm run docker:compose:up

# 4. Commit and push
git add .
git commit -m "Description of changes"
git push origin main

# 5. Render automatically deploys the changes

로그 보기

로컬 개발:

# The server logs to stderr
npm run start:sse

Docker:

npm run docker:compose:logs

Render.com:

• 서비스 대시보드로 이동합니다

• "Logs" 탭을 클릭합니다

• 실시간 로그가 여기에 표시됩니다

API 엔드포인트

SSE 모드로 실행 중일 때, 서버는 다음 엔드포인트를 노출합니다:

상태 확인 응답 예시

{
  "status": "ok",
  "service": "yahoo-mail-mcp",
  "version": "1.0.0",
  "timestamp": "2025-01-11T12:34:56.789Z"
}

주요 변경 사항 및 마이그레이션 가이드

⚠️ v3.0.0 주요 변경 사항

버전 3.0.0은 UID 기반 작업을 도입하여 이메일과 상호작용하는 방식을 근본적으로 변경합니다. 이는 기존 코드를 업데이트해야 하는 주요 변경 사항입니다.

무엇이 변경되었나요

1. 매개변수 이름 변경: sequenceNumbers → uids

이제 모든 이메일 관리 도구는 sequenceNumbers(임시 위치) 대신 uids(영구 식별자)를 사용합니다.

// ❌ v2.x (OLD - sequence numbers)
read_email({ sequenceNumbers: [1, 2, 3] })
delete_emails({ sequenceNumbers: [5] })

// ✅ v3.0.0 (NEW - UIDs)
read_email({ uids: [510867, 510866, 510862] })
delete_emails({ uids: [510867] })

2. 응답 형식: 일반 텍스트 → JSON

이제 모든 도구는 일반 텍스트 대신 구조화된 JSON을 반환합니다.

// ❌ v2.x response
"Email 1 of 10..."

// ✅ v3.0.0 response
{
  "emails": [...],
  "totalCount": 10,
  "returned": 10
}

3. 새로운 필수 워크플로우

이제 작업을 수행하기 전에 반드시 list_emails 또는 search_emails에서 UID를 가져와야 합니다.

// Step 1: Get UIDs
const result = list_emails({ count: 10 });
// Returns: { emails: [{ uid: 510867, ... }, { uid: 510866, ... }] }

// Step 2: Use UIDs for operations
const uidsToDelete = [510867, 510866];
delete_emails({ uids: uidsToDelete });

UID가 더 좋은 이유

시퀀스 번호 (v2.x):

• ❌ 이메일이 삭제되면 변경됩니다

• ❌ 위치 기반(이메일 #1, #2, #3)

• ❌ 작업 사이에 유효하지 않게 될 수 있습니다

• ❌ 혼란과 오류를 유발합니다

UID (v3.0.0):

• ✅ IMAP 서버가 할당하는 영구 식별자

• ✅ 다른 이메일이 삭제되어도 절대 변경되지 않습니다

• ✅ 이메일이 영구 삭제될 때까지 항상 유효합니다

• ✅ 일괄 작업에 안정적입니다

마이그레이션 체크리스트

• 모든 도구 호출에서 sequenceNumbers 대신 uids 매개변수를 사용하도록 업데이트

• 코드가 먼저 list_emails 또는 search_emails에서 UID를 가져오도록 업데이트

• 일반 텍스트가 아닌 JSON 응답을 처리하도록 코드 업데이트

• 일괄 작업이 모든 UID를 처리하는지 테스트(v3.0.0에서 심각한 일괄 작업 버그 수정)

• 새로운 기능 검토: 페이지네이션, 강화된 메타데이터, 고급 검색, 폴더 지원

v3.0.0의 새로운 기능

1. 강화된 메타데이터: 모든 이메일에 uid, size, flags, hasAttachments 포함

2. 페이지네이션: list_emails에서 offset 및 limit 매개변수 지원

3. 고급 검색: search_emails는 날짜 범위, 보낸 사람 필터, 읽지 않은 메일만 지원

4. 폴더 지원: 모든 도구에서 folder 매개변수 지원(기본값: INBX)

5. list_folders: 사용 가능한 IMAP 폴더를 확인하는 새 도구

6. 정확한 일괄 작업: 첫 번째 UID만 처리되던 심각한 버그 수정

7. 향상된 오류 처리: 더 나은 타임아웃 및 연결 오류 메시지

MCP 도구

list_emails

최근 이메일을 강화된 메타데이터(UID, 크래매*데이터) 및 페이지네이션 지원과 함께 나열합니다.

매개변수:

• count (선택): 가져올 이메일 수 (기본값: 10, 최대: 50)

• folder (선택): 리스트할 폴더 (기본값: 'INBOX'). 사용 가능한 폴더를 보러려면 list_folders를 사용하세요

• offset (선택): 페이지네이션을 위해 건너 일 메일 수 (기본값:0)

응답: 각 이메일의 강화된 메타데이터를 포험하는 emails 배열이 담긴 JSON:

• uid: 영구 IMAP UID (모든 작업에서 이 강을 시용)

• sequenceNumber: 폴더 내 위치 (참고용으로만 사용, 동작에 미사용)

• from: 발신자 주소

• subject: 이메일 제목

• date: RFC 2822 형식 날짜

• size: 이메일 용량 (바이트)

• flags: IMAP 플래그 배열 (예: ['\\Seen'], ['\\Flaged'])

• hasAtachments: 이메일 첨부 드존 유무를 나타는 불리언 값

예시:

// List 20 most recent emails
list_emails({ count: 20 })

// List emails with pagination (skip first 10)
list_emails({ count: 10, offset: 10 })

// List emails from Sent folder
list_emails({ count: 15, folder: "Sent" })

read_email

UID을 사용하여 이메일의 전체 내영을 읽습니다 (배치 읽기 지원).

매개변수:

• uids (필수): 읽을 UID 배열 (list_emails 또는 search_emails에서 UID 가져오기)

• folder (선택): 이메일이 포함된 폴더 (기본값: 'INBOX')

응답: 본문 내용이 포함된 강화된 이메일 데이터가 담긴 JSON

예시:

// Read a single email
read_email({ uids: [510867] })

// Read multiple emails
read_email({ uids: [510867, 510866, 510862] })

// Read email from Sent folder
read_email({ uids: [510867], folder: "Sent" })

search_emails

날짜 범위, 보낸 사람, 읽지 않은 상태 필터를 지원하는 고급 검색.

매개변수:

• query (선택): 제목 또는 보낸 사람 검색어 (날짜만 검색할 경우 비워 둘 수 있음)

• count (선택): 반환할 결과 수 (기본값: 10, 최대: 50)

• dateFrom (선택): 이 날짜부터 이메일 필터링 (ISO 8601 또는 RFC 2822 형식)

• dateTo (선택): 이 날짜까지의 이메일 필터링 (ISO 8601 또는 RFC 2822 형식)

• sender (선택): 특정 보낸 사람 이메일 주소 또는 이름으로 필터링

• unreadOnly (선택): 읽젝 않은 이메일만 확인 (기본값: false)

• folder (선택): 검색할 폴더 (기본값: 'INBOX')

응답: emails 배열, totalMatches, returned, query, filters, folder를 포함하는 JSON

예시:

// Basic search
search_emails({ query: "invoice", count: 15 })

// Search unread emails only
search_emails({ query: "meeting", unreadOnly: true })

// Search by date range
search_emails({ dateFrom: "2025-01-01", dateTo: "2025-01-31" })

// Search by sender
search_emails({ sender: "boss@company.com" })

// Combined filters
search_emails({
  query: "report",
  sender: "team@company.com",
  dateFrom: "2025-01-15",
  unreadOnly: true
})

list_folders

Yahoo Mail 계정에서 사용 가능한 모든 IMAP 폴더를 확인합니다.

매개변수: 없음

응답: name, path, delimiter, children를 포함하는 폴더 객체 배열이 담긴 JSON

예시:

// List all folders
list_folders()

// Example response:
// {
//   "folders": [
//     { "name": "INBOX", "path": "INBOX" },
//     { "name": "Sent", "path": "Sent" },
//     { "name": "Trash", "path": "Trash" },
//     { "name": "Archive", "path": "Archive" }
//   ]
// }

delete_emails

UID를 사용하여 이메일을 휴지통 폴더로 이동합니다(소프트 삭제 - 이메일 복구 가능음).

ave:

• uids (필수): 삭제한 UID 그룹 (list_emails 또는 search_emails 서 UID 가져오기)

• folder (선택): 원본 폴더 (기본값: 'INBOX')

응답: 처리된 이메일 수와 함께 성공/실패 메시지

예시:

// Delete a single email
delete_emails({ uids: [510867] })

// Delete multiple emails
delete_emails({ uids: [510867, 510866, 510862, 510856] })

// Delete from Sent folder
delete_emails({ uids: [510867], folder: "Sent" })

archive_emails

장기 보안을 위애 UID를 사용하여 이메일을 아카이브 폴더로 이종합니다.

매`변수:

• uids (필수): 보관할 UID 배열

• folder (선택): 원본 폴더 (기본값: 'INBOX')

답: 처리된 이메일 수와 함께 성공/실패 메시지

예시:

// Archive a single email
archive_emails({ uids: [510867] })

// Archive multiple emails
archive_emails({ uids: [510867, 510866, 510862, 510851] })

mmark_as_read

Seen 플래그를 추가하여 UID로 이메일을 읽음 처리합니다.

매개변수:

• uids (필수): 읽음으로 표시할 UID 배열

• folder (선택): 이메일이 포함된 폴더 (기본값: 'INBOX')

응답: 처리된 이메일 수와 함께 성공/실패 메시지

예시:

// Mark a single email as read
mark_as_read({ uids: [510867] })

// Mark multiple emails as read
mark_as_read({ uids: [510867, 510866, 510862, 510851, 510865] })

mark_as_unread

Seen 플래그를 제거하여 UID로 이메일을 읽지 않음으로 표시합니다.

매개변수:

• uids (필수): 읽지 않음으로 표시할 UID 배열

• folder (선택): 이메일이 포함된 폴더 (기본값: 'INBOX')

응답: 처리된 이메일 수와 함께 성공/실패 메시지

예시:

// Mark a single email as unread
mark_as_unread({ uids: [510867] })

// Mark multiple emails as unread
mark_as_unread({ uids: [510869, 510867, 510866] })

flag_emails

Flagged 플래그를 추가하여 UID로 이메일을 중요/별표로 표시합니다.

매개변수:

• uids (필수): 플래그할 UID 배열

• folder (선택): 이메일이 포함된 폴더 (기본값: 'INBOX')

응답: 처리된 이메일 수와 함께 성공/실패 메시지

예시:

// Flag a single email
flag_emails({ uids: [510867] })

// Flag multiple emails
flag_emails({ uids: [510851, 510865, 510864] })

unflag_emails

Flagged 플래그를 제거하여 UID로 이메일에서 플래그/별표를 제거합니다.

매개변수:

• uids (필수): 플래그를 제거할 UID 배열

• folder (선택): 이메일이 포함된 폴더 (기본값: 'INBOX')

응답: 처리된 이메일 수와 함께 성공/실패 메시지

예시:

// Unflag a single email
unflag_emails({ uids: [510867] })

// Unflag multiple emails
unflag_emails({ uids: [510867, 510866, 510862] })

move_emails

UID를 사용하여 이메일을 지정된 폴더로 이동합니다.

매개변수:

• uids (필수): 이동할 UID 배열

• folderName (필수): 대상 폴더 이름 (예: "Work", "Personal", "Archive")

• sourceFolder (선택): 원본 폴더 (기본값: 'INBOX')

응답: 처리된 이메일 수와 함께 성공/실패 메시지

예시:

// Move a single email to Work folder
move_emails({ uids: [510867], folderName: "Work" })

// Move multiple emails to Personal folder
move_emails({ uids: [510867, 510866, 510862], folderName: "Personal" })

// Move from Sent to Archive
move_emails({ uids: [510867], folderName: "Archive", sourceFolder: "Sent" })

성능 고려 사항

Render.com 무료 티어

• 비활성 후 절전: 요청이 15분 없으면 서비스가 절전됩니다

• 깨어나는 시간: 첫 요청은 30-60초가 걸립니다

• 월간 시간: 월 750시간(중간 정도 사용에 충분)

• 업그레이드: $7/월 (Starter 플랜, 항상 켜짐)

IMAP 성능

• 연결 풀링: 각 요청에 새 IMAP 연결이 생성됩니다

• 타임아웃:연결 및 인증에 30초

• 속도 제한: Yahoo는 과도한 요청을 제한할 수 있습니다

• 권장사항: 가능하면 클라이언트 측에서 결과 캐시

교차 플랫폼 호환성

이 프로젝트는 다음 환경에서 완벽하게 작동하도록 설계되었습니다:

• Windows 10/11 PowerShell 또는 Command Prompt

• Linux (Ubuntu, Debian, Fedora 등)

• macOS (Intel 및 Apple Silicon)

• Docker Desktop (Windows, Mac, Linux)

• WSL2 (Windows Subsystem for Linux)

줄 바꿈

• .gitattributes는 저장소에서 LF 줄 바꿈을 보장합니다

• Windows (CRLF) 및 Linux (LF)에서 올바르게 작동합니다

• Docker는 컨테이너 내부에서 LF를 사용합니다

경로 처리

• 코에서 모드 경는 슬래시 (/)를 사합니다

• path.join()이플랫폿 호안성를 위한해 사됩니다

• Windos 백슬래시와 Unix 슬래시 모두 지원 합니다

기기여

1. 저앙소를 포크합ㅁ\

2. 특feature: 키: git checkout -b feature-name

3. 변 경 사항\

4. Hydra Windows와 Linux에서 테(수 있을 경우)\n5. Commit: git comm -am "Add feature"

5. Push: git push origin feature-name

6. Pull Request를 만든다

라이런스

MIT 라이런스 - 상세 내용은 LICENSE 파일을 참조하세요

지원

• Issues: 버그는 https://github.com/yourusername/yahoo-mail-mcp-server/issues에 보고하세요

• Discussions: GitHub Discussions에 질문올 시작

• MCP 문서: https://modelcontextprotocol.io

변경 이력

v3.0.0 (2025-01-18) - UID.exeCL

BREAKING CHANGEES:

• ** 모든 도구가 이제 sequenceNumbers 대신 uids 매개변수를 사용합니다.

• 응답 형식이일 텍스트에서 구조화된 JSON으로 변경됨습니다.

• UID는 이메일이 삭제되더라도 변경되지 않는 영구 식별자입니다.

New Features:

• 강화된 메타데이터: 모든 이메일에 uid, size, flags, hasAttachments가 포함됩니다

• 페이지네이션 지원: list_emails가 offset 및 limit 매개변수를 지원합니다

• 고급 검색 필터: dateFrom, dateTo, sender, unreadOnly 매개변수

• 폴더 지원: 모든 도구가 folder 매개변수를 지원합니다(기본값: INBOX)

• 새 도구: 사용 가능한 IMAP 폴더를 탐색하는 list_folders

• 향상된 오류 처리: Render 스핀다운 감지를 포함한 타임아웃 및 연결 오류 메시지 개선

버그 수정:

• 중대한 버그 수정: 배치 작업에서 첫 번째 UID만 처리되던 오류를 수정했습니다.

• 모든 배치 작업이 이제 배열의 모든 UID를 정확하게 처리합니다.

• 성공/실패 메시지가 이제 처리된 이메일의 정확한 개수를 보고합니다.

마이그레이션 가이드:

• 모든 도구 호출에서 sequenceNumbers를 uids로 교체하세요.

• UID는 list_emails 또는 search_emails 응답에서 가져오세요.

• 일반 텍스트 대신 JSON 응답을 처리하도록 코드를 업데이트하세요.

• 자세한 내용은 위 "Breaking Changes & Migration Guide"의 섹션을 참조하세요.

v2.0.1 (2025-01-17)

• 수정: 모든 이메일 작업에 대한 입력 검증 강화

• 잘못된 시퀀스 번호로 인한 IMAP 오류를 방지하는 공용 검증 헬퍼 추가

• 디버깅이 쉽도록 오류 메시지 개선

v2.0.0 (2025-01-16)

• Breaking Change: read_email은 이제 sequenceNumber(단일 숫자) 대신 sequenceNumbers(배열)를 사용합니다.

• 배치 작업을 지원하는 전체 이메일 관리 기능이 추가되었습니다.

• 새 도구 7개: delete_emails, archive_emails, mark_as_read, mark_as_unread, flag_emails, unflag_emails, move_emails

• 모든 수정 작업이 배치 처리를 지원합니다.

• 되돌릴 수 있는 작업(소프트 삭제, 영구 삭제 없음)으로 보안이 강화되었습니다.

v1.0.0 (2025-01-11)

• 최초 릴리스

• stdio 및 SSE 전송 지원

• Docker 및 Docker Compose 지원

• Render.com 배포 구성

• 크로스 플랫폼 호환(Windows/Linux)

• 핵심 도구 3종: list_emails, read_email, search_emails

감사의 말

• @modelcontextprotocol/sdk로 제작되었습니다

• IMAP 접속에 imap을 사용합니다

• 이메일 파싱에 mailparser를 사용합니다

• Render.com에 배포됩니다

FAQ

Q: Gmail이나 다른 이메일 제공업체에서도 사용할 수 있나요?

A: 현재 이 서버는 Yahoo Mail용으로 구성되어 있습니다. 다른 제공업체를 지원하려면 server.js의 IMAP 구성(166~179줄)을 수정해야 합니다.

Q: 제 이메일 계정에 사용해도 안전한가요?

A: 네! 이 서버는 계정의 기본 비밀번호가 아닌 앱별 비밀번호를 사용하며, 모든 수정 작업은 되돌릴 수 있습니다. 삭제 작업은 이메일을 휴지통으로 옮기며(복구 가능), 서버는 이메일을 영구 삭제하거나 사용자를 대신해 이메일을 보내지 않습니다.

Q: Render에서 실행하는 비용은 얼마인가요?

A: 무료 요금제로 월 750시간을 제공하며, 보통 사용량에는 충분합니다. 항상 가동되는 서비스가 필요하면 스타터(Starter) 요금제가 월 $7입니다.

Q: 다른 클라우드 플랫폼에서도 실행할 수 있나요?

A: 네! Docker 구성을 지원하는 모든 플랫폼에서 사용할 수 있습니다(AWS ECS, Google Cloud Run, Azure Container Instances, Heroku, Fly.io 등).

Q: 컴퓨터를 계속 실행하고 있어야 하나요?

A: 아니요! Render.com(또는 다른 클라우드 플랫폼)에 배포하면 서버는 클라우드에서 독립적으로 실행됩니다.

Q: 배포 후 서버를 어떻게 업데이트하나요?

A: GitHub에 변경 사항을 푸시하기만 하면 됩니다. Render가 푸시를 자동으로 감지하여 서비스를 다시 배포합니다.

Q: 여러 사용자가 배포된 서버를 같이 사용할 수 있나요?

A: 서버는 단일 Yahoo Mail 계정(환경 변수에 설정된 계정)에 연결됩니다. 각 사용자는 자신의 이메일 계정을 위해 별도로 배포해야 합니다.

Q: 앱별 비밀번호를 잊으면 어떻게 하나요?

A: https://login.yahoo.com/account/security/app-passwords에서 새 비밀번호를 생성한 뒤 Render 환경 변수(Settings > Environment)에서 업데이트하면 됩니다.

다음 단계

배포에 성공한 뒤:

1. ✅ 헬스 엔드포인트를 확인합니다

2. ✅ Claude.ai에 연결합니다

3. ✅ 이메일 목록을 확인해 봅니다

4. ✅ 이메일 몇 개를 읽어 봅니다

5. ✅ 받은 편지함을 검색해 봅니다

6. 🎉 Yahoo Mail MCP 서버를 즐겨 보세요!

즐거운 코딩 되세요! 질문이나 문제가 있으시면 GitHub에 이슈를 남겨 주세요.