agentmail-mcp

Establishes secure connections to email accounts (Gmail, Outlook, etc.) through the Model Context Protocol, enabling AI agents to authenticate and maintain persistent sessions without storing credentials in agent memory. Uses MCP's resource-based architecture to abstract email provider APIs behind a standardized interface, allowing multiple email accounts to be registered and switched dynamically at runtime.

Retrieves emails from connected accounts with support for filtering by sender, subject, date range, and read status, plus cursor-based pagination for handling large mailboxes. Implements lazy-loading to avoid overwhelming agent context with full email bodies, returning metadata-first results that agents can selectively expand. Uses MCP's tool calling interface to expose filter parameters as structured function arguments.

Fetches full email message bodies including HTML/plain text content and attachment metadata (filename, MIME type, size) through MCP tools. Handles MIME parsing server-side to extract multipart content, returning structured text and attachment references that agents can selectively download. Supports both inline content and file attachments without embedding binary data in agent context.

Sends emails through connected accounts with support for plain text, HTML content, attachments, and CC/BCC recipients. Implements template substitution (variable replacement in subject/body) server-side to avoid exposing template logic to agents. Uses MCP tool calling to validate recipient addresses and attachment paths before sending, with optional draft preview before commit.

Lists, creates, and moves emails between folders (labels in Gmail, folders in Outlook) through MCP tools. Implements folder hierarchy traversal and supports both standard folders (Inbox, Sent, Trash) and custom user-created folders. Moves are atomic operations that update email state server-side, with support for bulk operations (move multiple emails in one call) to reduce round-trips.

Updates email state flags (read/unread, starred, flagged) through MCP tools with support for bulk operations. Implements atomic state transitions (mark as read, unread, spam, trash) with server-side validation to prevent invalid state changes. Supports conditional marking (e.g., mark all unread emails from sender X as read) through filter-then-mark patterns.

Provides advanced email search through MCP tools supporting full-text search, date ranges, sender/recipient filtering, and subject matching. Implements server-side query parsing to convert natural language filters into provider-specific search syntax (Gmail query language, Outlook KQL). Results are paginated and ranked by relevance, with optional sorting by date or sender.

Implements the Model Context Protocol specification for email operations, exposing email accounts as MCP resources and email operations as MCP tools with standardized request/response schemas. Handles resource lifecycle (connect, disconnect, list), tool parameter validation, and error responses according to MCP spec. Supports MCP's sampling feature for streaming large email lists and implements proper resource cleanup on disconnection.