MCP server for IMAP email operations with persistent encrypted cache. Designed for AI assistants (Claude Code, Claude Desktop) to read, search, organize, and draft emails on your behalf.
Most email MCP servers rely on AppleScript or native mail client APIs, which choke on large mailboxes (100K+ emails) and require the mail app to be running. IMAP-MCP talks directly to the IMAP server and caches everything locally in SQLite, so you can:
- Work with massive mailboxes (300K+ emails) without timeouts or memory issues -- the cache handles pagination and incremental loading
- Analyze email offline -- once cached, all queries run against the local database with zero server load, making it fast even on slow or metered connections
- Feed email data to other tools -- use cached emails as context for AI assistants to create tasks from action items, track unanswered emails, summarize threads, generate follow-up drafts, extract contacts, or build dashboards
- Process email at scale -- sort thousands of emails into folders, bulk-archive by sender, detect patterns across months of correspondence -- all without hammering your IMAP server
The local cache turns your mailbox into a queryable database that AI assistants can explore freely without worrying about rate limits, connection timeouts, or server availability.
- Full IMAP access -- read, search, move, copy, flag, archive, and draft emails
- Persistent SQLite cache with optional AES encryption (Fernet) -- emails and attachments stored locally for fast offline access
- Cross-platform secure credential storage via OS keyring (macOS Keychain / Windows Credential Locker / Linux SecretService)
- Flexible cache loading -- recent N emails, new-only, older (paginate backwards), or date range
- Cache-first reads -- subsequent queries served from local cache without hitting the IMAP server
- IMAP IDLE watching for real-time notifications across multiple mailboxes
- Auto-archive -- automatically archive emails from configured sender patterns
- Draft composition with configurable signature (text and HTML)
- Bulk email sorting via MCP tools -- move thousands of emails into folders by sender patterns
All sensitive credentials are stored in the OS keyring -- the native secure storage on each platform:
| Platform | Backend |
|---|---|
| macOS | Keychain (protected by Touch ID / login password) |
| Windows | Windows Credential Locker |
| Linux | SecretService (GNOME Keyring / KDE Wallet) |
The credentials.password field in config.json should be left empty. Passwords are saved to the keyring via imap-mcp --set-password and retrieved automatically at runtime. No plaintext passwords are ever written to disk.
When cache.encrypt: true, the local SQLite database containing your emails, bodies, and attachments is AES-encrypted (Fernet / AES-128-CBC + HMAC-SHA256):
- The database lives entirely in memory while the server runs
- On disk, only an encrypted snapshot exists (
.db.enc) -- it is unreadable without the key - The encryption key is auto-generated on first use and stored in the OS keyring under the service
imap-mcp-cache - If someone copies the
.db.encfile to another machine, they cannot decrypt it -- the key only exists in the keyring of the original machine - The encrypted file is updated atomically (temp file + rename) to prevent corruption
- Auto-flush every 50 write operations + forced flush after bulk operations (
load_cache,sync_emails)
When cache.encrypt: false, a plain SQLite file is written to disk with WAL journaling. This is recommended for very large mailboxes (100K+ emails) where holding the entire database in memory would consume too much RAM.
- UIDVALIDITY tracking: if the IMAP server reassigns UIDs (mailbox recreation), the cache for that mailbox is automatically purged and rebuilt
- Namespace auto-detection: the server automatically handles IMAP servers that require
INBOX.prefix for folder names (e.g., Dovecot, Jino)
# Install from local checkout
pipx install /path/to/IMAP-MCP
# Or install from GitHub
pipx install git+https://github.com/newlc/IMAP-mcp.git
# Store your IMAP password securely in the OS keyring
# (this will verify the connection before saving)
imap-mcp --set-password --config /path/to/config.json
# Add to Claude Code (project-level, current project only)
claude mcp add imap-mcp /path/to/imap-mcp -- --config /path/to/config.json
# Add to Claude Code (global, available in all projects)
claude mcp add --scope user imap-mcp /path/to/imap-mcp -- --config /path/to/config.jsonAdd the following to your claude_desktop_config.json (typically at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"imap-mcp": {
"command": "imap-mcp",
"args": ["--config", "/path/to/config.json"]
}
}
}If you installed with pipx, use the full path to the binary:
{
"mcpServers": {
"imap-mcp": {
"command": "/Users/yourname/.local/bin/imap-mcp",
"args": ["--config", "/path/to/config.json"]
}
}
}Add to your .vscode/mcp.json (or create it):
{
"servers": {
"imap-mcp": {
"command": "imap-mcp",
"args": ["--config", "/path/to/config.json"]
}
}
}If installed via pipx, use the full path:
{
"servers": {
"imap-mcp": {
"command": "/Users/yourname/.local/bin/imap-mcp",
"args": ["--config", "/path/to/config.json"]
}
}
}Add to your .cursor/mcp.json in the project root (or ~/.cursor/mcp.json for global):
{
"mcpServers": {
"imap-mcp": {
"command": "imap-mcp",
"args": ["--config", "/path/to/config.json"]
}
}
}With pipx:
{
"mcpServers": {
"imap-mcp": {
"command": "/Users/yourname/.local/bin/imap-mcp",
"args": ["--config", "/path/to/config.json"]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"imap-mcp": {
"command": "imap-mcp",
"args": ["--config", "/path/to/config.json"]
}
}
}Add a snippet to your project instructions file so the AI assistant knows how to use the email server:
## Email
Use the `imap-mcp` MCP server to access email. Workflow:
1. Call `auto_connect` first (reads config.json and credentials from keyring).
2. Use `load_cache` with mode "recent" to populate the local cache.
3. Use `fetch_emails`, `search_emails`, `get_email` etc. to read emails.
These will be served from cache when possible.
4. Use `move_email`, `archive_email`, `flag_email` to organize.
5. Use `save_draft` to compose replies (drafts appear in the mail client for review before sending).
6. Use `process_auto_archive` with `dry_run: true` to preview, then without to archive.Copy config.json.example to config.json and edit:
imap-mcp --set-password --config /path/to/config.jsonThis will:
- Read the username from
config.json - Prompt for the password
- Test the IMAP connection
- Store the password in the OS keyring on success
To remove a stored password:
imap-mcp --delete-password --config /path/to/config.jsonEach email account requires its own config.json and its own MCP server instance. Example with two accounts:
# Store passwords
imap-mcp --set-password --config ~/mail/work-config.json
imap-mcp --set-password --config ~/mail/personal-config.json
# Add both to Claude Code
claude mcp add imap-work /path/to/imap-mcp -- --config ~/mail/work-config.json
claude mcp add imap-personal /path/to/imap-mcp -- --config ~/mail/personal-config.jsonClaude will see both as separate MCP servers and can access either account by name.
The load_cache tool downloads emails (with bodies and attachments) into the local SQLite cache for offline access. It supports four modes:
| Mode | Description | Key parameters |
|---|---|---|
recent |
Load the last N emails (newest first) | count (default: 100) |
new |
Only emails newer than the most recent cached email | -- |
older |
Go further back in time: N emails older than the oldest cached | count (default: 100) |
range |
Emails within a specific date range | since, before (ISO dates) |
All modes are incremental -- emails already in the cache are skipped.
# Load the 200 most recent emails
load_cache(mailbox="INBOX", mode="recent", count=200)
# Check for new emails since last cache load
load_cache(mailbox="INBOX", mode="new")
# Go further back: load 100 older emails
load_cache(mailbox="INBOX", mode="older", count=100)
# Load emails from January 2026
load_cache(mailbox="INBOX", mode="range", since="2026-01-01", before="2026-02-01")
Use get_cache_stats to see how many emails are cached, database size, and encryption status.
| Tool | Description |
|---|---|
auto_connect |
Connect using config.json + keyring credentials (recommended) |
connect |
Manual IMAP connection to a host |
authenticate |
Manual login with username/password |
disconnect |
Close connection and stop watchers |
| Tool | Description |
|---|---|
list_mailboxes |
List all mailbox folders |
select_mailbox |
Open a mailbox folder |
create_mailbox |
Create a new folder |
get_mailbox_status |
Get message count, unseen, UIDNEXT, etc. |
| Tool | Description |
|---|---|
fetch_emails |
Fetch emails with limit/offset, date filters |
get_email |
Get complete email (headers + body + attachments) by UID |
get_email_headers |
Get headers only (faster) |
get_email_body |
Get body as text or HTML |
get_attachments |
List attachment metadata |
download_attachment |
Download attachment content (base64) |
get_thread |
Get email conversation thread |
| Tool | Description |
|---|---|
search_emails |
Free-text or IMAP SEARCH syntax |
search_by_sender |
Search by sender address |
search_by_subject |
Search by subject text |
search_by_date |
Search by date range |
search_unread |
Get all unread emails |
search_flagged |
Get all flagged/starred emails |
| Tool | Description |
|---|---|
mark_read |
Mark emails as read |
mark_unread |
Mark emails as unread |
flag_email |
Add a flag (e.g. \Flagged, \Important) |
unflag_email |
Remove a flag |
move_email |
Move emails to another folder |
copy_email |
Copy emails to another folder |
archive_email |
Move emails to Archive folder |
save_draft |
Save a draft with optional signature |
| Tool | Description |
|---|---|
get_unread_count |
Unread email count |
get_total_count |
Total email count in mailbox |
| Tool | Description |
|---|---|
get_cached_overview |
Get in-memory overview of inbox/next/waiting/someday |
refresh_cache |
Force refresh the in-memory cache |
start_watch |
Start IDLE watchers on all configured folders |
stop_watch |
Stop all IDLE watchers |
idle_watch |
Watch a single mailbox temporarily (with timeout) |
| Tool | Description |
|---|---|
sync_emails |
Download emails for a date range into SQLite (incremental) |
load_cache |
Flexible cache loader (recent/new/older/range modes) |
get_cache_stats |
Cache statistics (count, size, encryption status) |
| Tool | Description |
|---|---|
get_auto_archive_list |
List auto-archive sender patterns |
add_auto_archive_sender |
Add a sender/domain to auto-archive |
remove_auto_archive_sender |
Remove a sender from auto-archive |
reload_auto_archive |
Reload sender list from file |
process_auto_archive |
Archive matching emails (supports dry_run) |
- Python 3.10+
- Dependencies (installed automatically):
imapclient>= 3.0.0 -- IMAP protocol clientmcp>= 1.0.0 -- Model Context Protocol SDKpydantic>= 2.0.0 -- data validationkeyring>= 25.0.0 -- OS keyring integrationcryptography>= 43.0.0 -- AES encryption for cache
MIT
{ // IMAP server connection "imap": { "host": "imap.example.com", // IMAP server hostname "port": 993, // IMAP port (993 = SSL/TLS) "secure": true // Use SSL/TLS }, // SMTP server (used for saving drafts with proper headers) "smtp": { "host": "smtp.example.com", "port": 587 }, // Credentials -- leave password EMPTY and use --set-password "credentials": { "username": "your-email@example.com", "password": "" }, // User identity (used in From header and signature for drafts) "user": { "name": "Your Name", "email": "your-email@example.com", "signature": { "enabled": true, "text": "\n\n--\nYour Name\nTel: +1 234 567890", "html": "<br><br><div style=\"color:#666\">--<br><b>Your Name</b><br>Tel: +1 234 567890</div>" } }, // Mailbox folder names (adjust to match your IMAP server) "folders": { "inbox": "INBOX", "next": "Next", // GTD-style action folders "waiting": "Waiting", "someday": "Someday", "archive": "Archive", "drafts": "Drafts" }, // In-memory cache for the IDLE watcher "cache": { "enabled": true, // Auto-start IDLE watcher on connect "ttl_seconds": 300 // Cache TTL for overview queries }, // Persistent SQLite cache (add these fields to enable) // "cache": { // "db_path": "~/.imap-mcp/cache.db", // Path to SQLite database // "encrypt": true // true = in-memory DB + encrypted file on disk // // false = plain SQLite file (better for 100K+ emails) // }, // Auto-archive configuration "auto_archive": { "enabled": true, "senders_file": "auto_archive_senders.json" // JSON file with sender patterns } }