A Model Context Protocol server that gives AI assistants full access to Apple iCloud Mail through IMAP and SMTP. Search, read, send, reply, organize, and manage your iCloud mailbox -- all from Claude or any MCP-compatible client.
Built with Go and the mcp-go SDK. Ships as a single static binary for Linux, macOS, and Windows.
A Go-based MCP server for iCloud Mail via IMAP/SMTP — search, read, send, and manage emails through AI assistants.
MCP tool annotations (read-only, destructive, idempotent) for client-side safety
CI pipeline with tests, linting, and vulnerability scanning
Quick Start
# Install
go install github.com/rgabriel/mcp-icloud-email@latest
# Set credentials (app-specific password, not your main iCloud password)
export ICLOUD_EMAIL="[email protected]"
export ICLOUD_PASSWORD="xxxx-xxxx-xxxx-xxxx"
# Run
mcp-icloud-email
Or download a prebuilt binary from the Releases page.
Prerequisites
Go 1.21+ -- install (only needed when building from source)
iCloud account with two-factor authentication enabled
App-specific password -- required for IMAP/SMTP access
The server exposes 14 MCP tools. Each tool includes schema constraints and annotations indicating whether it is read-only, destructive, or idempotent.
search_emails
Search and list emails with optional filters. Returns email headers (not full bodies) for efficiency.
Parameter
Type
Default
Description
query
string
Search term for subject/body
folder
string
INBOX
Mailbox folder to search
last_days
integer
30
Only show emails from last N days
limit
integer
50
Max emails to return (max 200)
offset
integer
0
Skip first N results (for pagination)
unread_only
boolean
false
Only return unread emails
since
string
Start date (ISO 8601)
before
string
End date (ISO 8601)
Response includes count (returned), total (matching before offset/limit), and an array of email summaries.
get_email
Retrieve full email content including body text, HTML, headers, and attachment list.
Parameter
Type
Default
Description
email_id
string
(required)
Email UID
folder
string
INBOX
Mailbox folder
send_email
Compose and send a new email.
Parameter
Type
Default
Description
to
string/array
(required)
Recipient address(es)
subject
string
(required)
Subject line
body
string
(required)
Email body
cc
string/array
CC address(es)
bcc
string/array
BCC address(es)
html
boolean
false
Whether body is HTML
reply_email
Reply to an existing email. Automatically sets In-Reply-To and References headers.
Parameter
Type
Default
Description
email_id
string
(required)
Email UID to reply to
body
string
(required)
Reply body
folder
string
INBOX
Folder containing original email
reply_all
boolean
false
Reply to all recipients
html
boolean
false
Whether body is HTML
draft_email
Save an email as a draft. Supports reply drafts with automatic header threading.
Parameter
Type
Default
Description
to
string/array
(required)
Recipient address(es)
subject
string
(required)
Subject line
body
string
(required)
Email body
cc
string/array
CC address(es)
bcc
string/array
BCC address(es)
html
boolean
false
Whether body is HTML
reply_to_id
string
Original email ID for reply drafts
folder
string
INBOX
Folder of original email (for replies)
delete_email
Delete an email by moving it to trash, or permanently delete it.
Parameter
Type
Default
Description
email_id
string
(required)
Email UID
folder
string
INBOX
Mailbox folder
permanent
boolean
false
Permanently delete instead of trashing
move_email
Move an email from one folder to another.
Parameter
Type
Default
Description
email_id
string
(required)
Email UID
from_folder
string
INBOX
Source folder
to_folder
string
(required)
Destination folder
mark_read
Change the read/unread status of an email.
Parameter
Type
Default
Description
email_id
string
(required)
Email UID
folder
string
INBOX
Mailbox folder
read
boolean
true
true to mark read, false for unread
flag_email
Flag an email for follow-up with optional color.
Parameter
Type
Default
Description
email_id
string
(required)
Email UID
flag
string
(required)
follow-up, important, deadline, or none
folder
string
INBOX
Mailbox folder
color
string
red, orange, yellow, green, blue, purple
Set flag to none to remove all flags.
count_emails
Count emails matching filters without downloading message content.
Parameter
Type
Default
Description
folder
string
INBOX
Mailbox folder
last_days
integer
Only count from last N days
unread_only
boolean
false
Only count unread
list_folders
List all available mailbox folders. Takes no parameters.
create_folder
Create a new mailbox folder.
Parameter
Type
Default
Description
name
string
(required)
Folder name
parent
string
Parent folder for nesting (e.g. Work/Projects)
delete_folder
Delete a mailbox folder. Non-empty folders require explicit confirmation.
Parameter
Type
Default
Description
name
string
(required)
Folder name
force
boolean
false
Delete even if folder contains emails
System folders (INBOX, Sent, Trash) cannot be deleted.
get_attachment
Download an email attachment by filename.
Parameter
Type
Default
Description
email_id
string
(required)
Email UID
filename
string
(required)
Attachment filename
folder
string
INBOX
Mailbox folder
save_path
string
File path to save to (returns base64 if omitted)
Working with Large Inboxes
The server uses server-side IMAP SEARCH commands, so filtering happens on the mail server before any data is downloaded. Default settings are tuned for large mailboxes:
search_emails defaults to the last 30 days and a limit of 50
count_emails returns counts without fetching message content
get_email loads full body content on demand for individual messages
Recommended workflow:
Use count_emails to check how many emails match your criteria
Adjust last_days, since/before, or unread_only to narrow results
Use search_emails with offset and limit for pagination
Use get_email only for specific messages you need to read in full
Development
Building
make build # Build binary
make test # Run tests with race detector
make lint # Run golangci-lint
make vet # Run go vet
make vuln # Run govulncheck
make all # vet + lint + test + build
make docker # Build Docker image
make tools # Install dev tools (golangci-lint, govulncheck)
Running Locally
export ICLOUD_EMAIL="[email protected]"
export ICLOUD_PASSWORD="xxxx-xxxx-xxxx-xxxx"
make run
Testing
The project includes 78+ table-driven tests covering all tool handlers, input validation, and error paths. Tests use mock implementations of the EmailService and EmailSender interfaces -- no live IMAP/SMTP connection required.
make test
Testing with MCP Inspector
Use the MCP Inspector to interactively test the server:
Middleware chain: Each tool call passes through logging -> timeout -> handler. The logging middleware assigns a UUID request ID and records tool name, duration, and outcome. The timeout middleware enforces a 60-second deadline.
Thread safety: The IMAP client uses a sync.Mutex to serialize access. Internal methods (lowercase) assume the caller holds the lock, preventing deadlocks from nested calls like DeleteEmail -> moveEmail.
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo MCP Icloud Email?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
MCP Icloud Email precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte MCP Icloud Email usa?
MCP Icloud Email roda localmente via stdio.
Quando MCP Icloud Email foi verificado pela última vez?
Última verificação: 2026-10-28. A Go-based MCP server for iCloud Mail via IMAP/SMTP — search, read, send, and manage emails through AI assistants.