App 암호 인증을 사용하여 iCloud Mail과 통합하기위한 Model Context Protocol (MCP) 서버. 이 서버는 iCloud의 IMAP 및 SMTP 서비스를 통해 이메일을 읽고, 전송 및 관리 할 수있는 도구를 제공합니다.

이 프로젝트의 개발 로그는 Hack Club의 Summer of Making에서 공유됩니다. 개발 여정을 따른다!

특징

• Secure 인증: 안전한 iCloud Mail 액세스를 위한 App-specific 암호 사용
• 이메일 관리: 읽기, 메일, 및 이메일 구성 -Mailbox 운영: 메일 박스 목록, 메시지 표시
• Attachment 지원: 이메일 첨부
• MCP 통합: MCP 호환 클라이언트와의 원활한 통합

필수품

1. ** iCloud 계정**: 사용 가능한 iCloud 계정이 필요합니다. 2.App Password: 메일 액세스의 앱 별 암호 생성:

• appleid.apple.com에 로그인
• "Sign-In and Security"로 이동 > “App-Specific Passwords”
• "Mail"의 새로운 암호 생성
• 이 암호를 안전하게 저장

설치

구성

서버는 환경 변수가 인증을 설정해야 합니다. 구성은 MCP 클라이언트 설정을 통해 이루어집니다:

iCloud Mail MCP Server

A Model Context Protocol (MCP) server for integrating with iCloud Mail using App Password authentication. This server provides tools to read, send, and manage emails through iCloud’s IMAP and SMTP services.

Development logs for this project are being shared on Hack Club’s Summer of Making. Check it out to follow the development journey!

Features

• Secure Authentication: Uses App-specific passwords for secure iCloud Mail access
• Email Management: Read, send, and organize emails
• Mailbox Operations: List mailboxes, mark messages as read
• Attachment Support: Handle email attachments
• MCP Integration: Seamless integration with MCP-compatible clients

Prerequisites

1. iCloud Account: You need an active iCloud account with Mail enabled
2. App Password: Generate an app-specific password for Mail access:
   • Sign in to appleid.apple.com
   • Go to “Sign-In and Security” > “App-Specific Passwords”
   • Generate a new password for “Mail”
   • Save this password securely

Installation

# Clone the repository
git clone https://github.com/minagishl/icloud-mail-mcp.git
cd icloud-mail-mcp

# Install dependencies using pnpm
pnpm install

# Build the project
pnpm run build

Configuration

The server requires environment variables to be set for authentication. Configuration is done through your MCP client settings:

Environment Variables (Required)

Add to your MCP server configuration:

{
  "icloud-mail-mcp": {
    "command": "node",
    "args": ["/path/to/icloud-mail-mcp/dist/index.js"],
    "env": {
      "ICLOUD_EMAIL": "[email protected]",
      "ICLOUD_APP_PASSWORD": "your-app-specific-password"
    }
  }
}

Available Tools

Email Operations

get_messages

Retrieve email messages from a specified mailbox.

Parameters:

• mailbox (string, optional): Mailbox name (default: “INBOX”)
• limit (number, optional): Maximum number of messages to retrieve (default: 10)
• unreadOnly (boolean, optional): Retrieve only unread messages (default: false)

send_email

Send an email through iCloud Mail.

Parameters:

• to (string or array, required): Recipient email address(es)
• subject (string, required): Email subject
• text (string, optional): Plain text email body
• html (string, optional): HTML email body

mark_as_read

Mark email messages as read.

Parameters:

• messageIds (array, required): Array of message IDs to mark as read
• mailbox (string, optional): Mailbox name (default: “INBOX”)

move_messages

Move messages between mailboxes.

Parameters:

• messageIds (array, required): Array of message IDs to move
• sourceMailbox (string, required): Source mailbox name
• destinationMailbox (string, required): Destination mailbox name