Model Context Protocol Email Bridgev0.1.0

Connect your email accounts to AI with Model Context Protocol

A secure, personal bridge that equips ChatGPT, Claude, and Cursor with read-only search, unread-safe message extraction, and owner-authorized sending across Gmail, Apple iCloud, and IMAP accounts.

Open Mailbox Console Inspect 7 MCP Tools

AES-256-GCM encrypted tokens10-minute ephemeral cacheRFC 3501 BODY.PEEK (no Seen mutation)

Live Protocol SimulationRealistic payloads & telemetry

142 ms

User Prompt to AI Agent

“Find any invoices received from Stripe this month.”

Model Context Protocol

tools/call → search_messages

JSON Input

{
  "account_id": "acc_icloud_01",
  "query": "from:stripe invoice",
  "mailbox": "INBOX",
  "limit": 3
}

result

JSON Output

{
  "messages": [
    {
      "id": "msg_9f82d1",
      "subject": "Your Stripe invoice for October 2026",
      "from": "invoicing@stripe.com",
      "date": "2026-10-18T14:32:00Z",
      "has_attachments": true,
      "snippet": "Payment received. Invoice #INV-2026-10 is attached."
    }
  ],
  "total": 1
}

Protocol invariant:IMAP EXAMINE · Preserves Unread Flag

Zero raw passwords stored

Multi-Provider Support

Works across your personal and work mailboxes

Consolidate your different mail accounts into a single unified Model Context Protocol interface.

Google Gmail

OAuth 2.0 PKCE

Connect seamlessly via Google OAuth. Read messages with minimal scopes, or grant incremental send access when needed.

Testing Mode 7-day token refresh
Incremental send permission
Zero password exposure

Apple iCloud Mail

App-Specific Password

Integrate your iCloud and @me.com mailboxes using dedicated Apple ID app passwords over secure SSL/TLS.

IMAP: imap.mail.me.com:993
SMTP: smtp.mail.me.com:587
Preserves push notification flags

Yandex Mail

App-Specific Password

Connect personal or domain Yandex inboxes securely with 2FA app passwords over encrypted protocols.

IMAP: imap.yandex.com:993
SMTP: smtp.yandex.com:465
Full Russian & Cyrillic charset support

Custom IMAP / SMTP

Standard TLS / SSL

Connect Fastmail, self-hosted Postfix/Dovecot, or enterprise email servers complying with RFC standards.

Enforced TLS certificate checks
Private loopback blocking
Configurable mailbox presets

Clean architectural boundaries

OmniMail MCP isolates your credentials, preserves mailbox state, and mediates every interaction between AI agents and your mailboxes.

AI ClientsMCP Consumers

ChatGPT (Custom Actions / MCP)
Claude Desktop & Claude Code
Cursor & Windsurf IDEs
Custom Autonomous MCP Agents

Interacts strictly through typed MCP tools with JSON schemas.

OmniMail MCP Core

Secure Bridge LayerEncrypted Transit

AES-256-GCM token storage
10-minute ephemeral encrypted cache
Owner-only Google sign-in & RLS
Strict request-origin verification

No email database storage. Content disappears after 10 minutes.

Mailbox ProvidersUpstream Targets

Google Gmail (OAuth 2.0 PKCE)
Apple iCloud (App Password + TLS)
Yandex Mail (App Password + SSL)
Custom IMAP / SMTP Servers

All TLS connections validated. Unencrypted plaintext refused.

Model Context Protocol Specification

The 7 standardized MCP email tools

OmniMail MCP exposes a cohesive, battle-tested tool surface designed specifically for LLM function calling and client sandboxes.

list_accountsRead

Enumerate all connected mail accounts, their provider types (Gmail, iCloud, Yandex, IMAP), and allowed capabilities.

Tool arguments (JSON)

{}

Read-only · Never connects to network

list_mailboxesRead

List folders and mailboxes for a specific account, including total message counts and system tags.

Tool arguments (JSON)

{
  "connectionId": "acc_icloud_01"
}

Read-only · IMAP LIST

search_messagesRead

Search mailboxes by text query, sender, date range, or folder with bounded result limits.

Tool arguments (JSON)

{
  "connectionId": "acc_icloud_01",
  "query": "from:stripe invoice",
  "label": "INBOX"
}

Preserves \Seen flag · EXAMINE mode

get_messageRead

Fetch a message's text body, headers, and attachment manifests without altering unread status.

Tool arguments (JSON)

{
  "connectionId": "acc_icloud_01",
  "messageId": "msg_9f82d1"
}

RFC 3501 BODY.PEEK · Ephemeral cache

get_attachmentRead

Download a specific attachment's exact binary bytes and MIME type by ID.

Tool arguments (JSON)

{
  "connectionId": "acc_icloud_01",
  "messageId": "msg_9f82d1",
  "attachmentId": "att_04a8b2"
}

Bounded transfer size (max 25 MB)

stage_attachmentsStorage

Stage outgoing attachment files into encrypted temporary storage prior to dispatching an email.

Tool arguments (JSON)

{
  "connectionId": "acc_icloud_01",
  "inlineFiles": [
    {
      "name": "invoice.pdf",
      "content_base64": "JVBERi0xLj..."
    }
  ]
}

AES-256-GCM · 10-minute auto-purge

send_messageWrite

Deliver an email to designated recipients with optional attachments and custom sender identity.

Tool arguments (JSON)

{
  "connectionId": "acc_icloud_01",
  "message": {
    "to": [
      "finance@company.internal"
    ],
    "subject": "Re: October SaaS Invoices",
    "text": "Invoice settled."
  }
}

Explicit send permission required

Privacy and security by design

Engineered with strict protocol invariants so you can safely grant language models access to your real communication workflows.

RFC 3501 EXAMINE & BODY.PEEK

Preserving unread status

Unlike typical email clients that silently set the \Seen flag on access, OmniMail MCP opens mailboxes in EXAMINE read-only mode and uses BODY.PEEK. AI can analyze your emails without clearing your unread notifications.

Enforced at runtime

Authenticated Additional Data (AAD)

AES-256-GCM authenticated encryption

Refresh tokens and app-specific passwords are sealed at rest with AES-256-GCM. Decryption keys are runtime-bound and sealed tokens are cryptographically locked to your user identity.

Enforced at runtime

Zero permanent message storage

10-minute ephemeral lifecycle

Emails, bodies, and attachments are never persisted into your database. Temporary caches and staged attachments exist solely to prevent upstream rate-limits and expire within 10 minutes.

Enforced at runtime

No accidental or autonomous sends

Dual-lock send authorization

Sending is disabled by default. An outgoing email requires both the account connection toggle and the MCP client permission to be explicitly switched on by the owner.

Enforced at runtime

Client Compatibility

Plug into the AI clients you already use

Connect ChatGPT, Claude, and developer IDEs via standard Model Context Protocol configuration.

ChatGPT Plus / Pro

Remote MCP / OAuth

Add OmniMail MCP as an authorized MCP tool in your ChatGPT workspace with one-click OAuth consent.

{
  "name": "OmniMail MCP",
  "url": "https://<your-domain>/mcp",
  "auth": "OAuth 2.0 (PKCE)"
}

Claude Desktop & Code

JSON Config

Add OmniMail to your claude_desktop_config.json file for seamless desktop workflow automation.

{
  "mcpServers": {
    "omnimail": {
      "url": "https://<your-domain>/mcp"
    }
  }
}

Cursor & Windsurf

IDE Extensions

Reference error reports, customer emails, and notification logs directly from your code editor.

{
  "mcpServers": {
    "mail": {
      "url": "https://<your-domain>/mcp"
    }
  }
}

Ready to connect your email to AI?

Set up your accounts, configure client permissions, and start interacting with your inbox securely through Model Context Protocol.

Open Mailbox Console Read Setup Guide