Skip to main content

​
How It Works

​
Architecture

email-connector is an MCP (Model Context Protocol) server that bridges Claude AI to your email inbox via IMAP and SMTP. MCP is Anthropic’s open standard for connecting AI models to external tools and data sources. 
┌──────────┐     MCP (HTTPS)     ┌─────────────────────┐     IMAP/SMTP     ┌──────────────┐
│          │ ◄────────────────► │                     │ ◄──────────────► │              │
│  Claude  │   Streamable HTTP   │  email-connector    │   TLS 1.3        │  Your email  │
│          │   Bearer token      │  (Fly.io)           │                   │  provider    │
└──────────┘                     └─────────────────────┘                   └──────────────┘
                                   │
                                   ├── OAuth 2.0 + PKCE (authorization)
                                   ├── AES-256-GCM (credential storage)
                                   └── Session management (30-min timeout)
When you ask Claude about your email, Claude sends an MCP tool call to email-connector. The server decrypts your credentials, opens a live IMAP connection to your inbox, retrieves the data, and returns it to Claude. No email content is ever stored.

​
Data Flow

​
Reading email

1. You ask Claude: "What are my unread emails?"
2. Claude calls the get_recent_emails MCP tool
3. email-connector receives the request with your Bearer token
4. Credentials are decrypted from the AES-256-GCM store
5. IMAP connection opened to your provider (e.g., imap.mail.me.com:993)
6. Unread messages fetched
7. IMAP connection closed, credentials cleared from memory
8. Results returned to Claude
9. Claude formats and displays your emails

​
Sending email

1. You tell Claude: "Reply to Sarah and say I'm available Thursday"
2. Claude calls the send_email MCP tool
3. email-connector decrypts credentials and opens SMTP connection
4. Email sent via your provider's SMTP server
5. SMTP connection closed
6. Confirmation returned to Claude

​
Security Model

Email credentials go through multiple layers of protection:
  1. App passwords only — your main account password is never used or requested
  2. AES-256-GCM encryption at rest — credentials are encrypted before storage
  3. Decrypted in memory only — credentials exist in plaintext only during an active IMAP/SMTP session
  4. Never logged — credentials never appear in application logs or error output
  5. Session-isolated — each tool call opens and closes its own IMAP connection

​
MCP Transport

email-connector uses Streamable HTTP — the current recommended MCP transport per Anthropic’s specification. SSE-only transport is deprecated.
EndpointMethodPurpose
/mcpPOSTInitialize or continue an MCP session
/mcpGETSSE upgrade for streaming responses
/mcpDELETEClose a session
/oauth/*GET/POSTOAuth 2.0 authorization server
/healthGETPublic health check

​
Available Tools

ToolDescription
get_recent_emailsFetch recent emails from any folder
search_emailsSearch by sender, subject, date, or keyword
get_emailGet full content of a specific email
list_mailboxesList all mailbox folders
list_providersList supported email providers
draft_emailCompose a draft without sending
send_emailSend an email via SMTP
mark_as_readMark a message as read
move_emailMove a message to another folder
See the MCP Tools Reference for full parameter documentation.

​
Session Management

MCP sessions are identified by the Mcp-Session-Id header. Sessions time out after 30 minutes of inactivity. When a session expires, Claude transparently creates a new one on the next request. The session store is in-memory by default. For multi-process deployments, replace the Map with Redis (see Self-Hosting).