home / mcp / mcp mail server

MCP Mail Server

Provides an MCP server for IMAP/SMTP email operations with AI assistants, including search, send, and attachment handling.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "yunfeizhu-mcp-mail-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mail-server"
      ],
      "env": {
        "IMAP_HOST": "your-imap-server.com",
        "IMAP_PORT": "993",
        "SMTP_HOST": "your-smtp-server.com",
        "SMTP_PORT": "465",
        "EMAIL_PASS": "your-password",
        "EMAIL_USER": "[email protected]",
        "IMAP_SECURE": "true",
        "SMTP_SECURE": "true"
      }
    }
  }
}

The MCP Mail Server provides a ready-to-use, AI-friendly MCP server that enables IMAP/SMTP email operations through natural language commands. You can search, read, send, and manage emails across mailboxes, handle attachments, and securely connect to your email services with TLS/SSL. This makes it easy to integrate email workflows with AI assistants and MCP clients for streamlined email management.

How to use

You will integrate this MCP server with an MCP client to perform email operations using natural language. Start by configuring the MCP client with the server details, then issue commands like asking for unread emails, searching by sender or subject, sending messages, or handling attachments. The server manages IMAP and SMTP connections automatically, so you can focus on your email workflows. Use queries such as asking for unread messages from today, listing available mail folders, or sending an email with an attachment. You can also reply to specific emails and manage attachments directly through your AI assistant.

How to install

Prerequisites: you need Node.js version 18 or higher and npm. You will install the MCP server globally, then configure it in your MCP client.

# Prerequisites: ensure Node.js 18+ is installed
node -v
npm -v

# Install the MCP mail server globally
npm install -g mcp-mail-server

Configure your MCP client to include the MCP server. Use the environment variables shown in the configuration examples to connect to your IMAP and SMTP services. After configuration, add the server under this MCP client’s settings so your AI assistant can start issuing email-related commands.

Example configuration blocks are provided for popular MCP clients. Each block shows how to wire the server with your email credentials and endpoints.

Configuration and usage notes

The server relies on environment-based configuration and supports TLS/SSL. You should provide your IMAP and SMTP details, including host, port, and secure flags, along with your email credentials. Never hardcode credentials in your applications; use secure environment management provided by your MCP client or deployment environment.

To get started quickly, add the following example to the MCP client configuration, replacing placeholders with your actual values.

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "IMAP_HOST": "your-imap-server.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "SMTP_HOST": "your-smtp-server.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "EMAIL_USER": "[email protected]",
        "EMAIL_PASS": "your-password"
      }
    }
  }
}

Security and best practices

Always enable TLS/SSL when connecting to IMAP and SMTP. Use App Passwords or OAuth where available, and keep credentials out of source code. Manage secrets through your MCP client’s secure vault or environment management features.

Usage examples

You can use natural language to perform a wide range of actions, such as connecting to your email servers, listing folders, finding unread messages, sending new emails, replying to messages, and downloading attachments. The server is designed to work with AI assistants to streamline email workflows.

Available tools

connect_all

Establish connections to both IMAP and SMTP servers so you can start performing email operations.

get_connection_status

Retrieve current connection status and server information to ensure your mail services are reachable.

disconnect_all

Terminate all active IMAP/SMTP connections gracefully.

open_mailbox

Open a specific mailbox or folder to work with its messages.

list_mailboxes

List all available mail folders in your connected account.

get_message_count

Return the total number of messages in the currently open mailbox.

get_unseen_messages

Fetch all unread messages in the current mailbox.

get_recent_messages

Retrieve recently received messages from the mailbox.

get_message

Retrieve a single email by its UID, with optional markSeen to update status.

get_messages

Retrieve multiple emails by their UIDs, with optional markSeen.

delete_message

Delete a message by its UID from the mailbox.

send_email

Send an email via SMTP with optional HTML/text body and attachments.

reply_to_email

Reply to a specific email, with options to include the original message and send to all recipients.

get_attachments

Get metadata for attachments associated with a specific email.

save_attachment

Download and save attachments to a local file path, with optional base64 return.