MCP Mail Server

An IMAP/SMTP email server based on the model context protocol, supporting email search, reading, sending, and management operations by AI assistants (such as Claude and Cursor) through natural language instructions.

Communication tools Developer tools #Email Management #AI Assistant #IMAP/SMTP #Protocol Service .TypeScript

rating : 2.5 points

downloads : 8.6K

update time : 2025-12-12

Open Site

What is MCP Mail Server?

MCP Mail Server is an intelligent email assistant server that allows you to manage emails using natural language through AI assistants (such as Claude, Cursor, etc.). You can tell the AI assistant what email operations you want to perform, just like having a conversation with a person, such as 'View today's unread emails' or 'Reply to the boss's email', and the server will automatically execute the corresponding IMAP/SMTP operations.

How to use MCP Mail Server?

It's very simple to use: 1) Install the server software; 2) Configure your email account information; 3) Add the server to your AI assistant configuration; 4) Start managing emails using natural language. There's no need to write code or learn complex email protocols throughout the process.

Use cases

Suitable for users who need to handle emails frequently, especially: busy professionals, team managers, customer service staff, researchers, and anyone who wants to improve email processing efficiency through AI. You can use it to quickly filter important emails, reply in batches, organize your inbox, etc.

Main Features

Intelligent Email Search

Supports multiple search methods: search by sender, subject, content, date, email size, etc. It can also find un-replied emails from specific senders.

Email Sending Function

Supports sending emails with HTML/plain text content and attachments. It can reply to specific emails and supports CC and BCC.

Secure Connection

Supports TLS/SSL encrypted connections to ensure the security of email transmission. It is recommended to use an app-specific password instead of a regular password.

Multi-client Support

Compatible with Claude Desktop, Cursor, and other AI assistants that support the MCP protocol. The configuration method is unified and simple.

Automatic Connection Management

Automatically handles the connections to IMAP and SMTP servers without the need for manual management of the connection status.

Multi-email Support

Allows access to and management of emails in the INBOX, Sent Items, and custom folders.

Advantages

Natural language operation: No need to learn complex commands. You can manage emails using daily language.

Improve efficiency: AI assistants can quickly perform repetitive tasks such as searching, filtering, and replying.

Cross-platform compatibility: Supports multiple AI assistants and email service providers.

Safe and reliable: Uses standard encryption protocols and supports app-specific passwords.

Simple configuration: Configure once through environment variables and use for a long time.

Limitations

Requires AI assistant support: You must use an AI tool that supports the MCP protocol.

Initial configuration requires technical knowledge: Setting environment variables may be a bit challenging for non-technical users.

Depends on network connection: Requires a stable network connection to the email server.

Some advanced email functions may not be supported: Such as complex email rules or filters.

How to Use

Install the Server

Install the MCP Mail Server software package globally via npm.

Configure Email Information

Set the necessary environment variables, including the email server address, port, email account, and password.

Add to AI Assistant

According to the AI assistant you are using (Claude Desktop or Cursor), add the MCP server settings to the configuration file.

Start Using

Restart the AI assistant, and then you can manage emails using natural language commands.

Usage Examples

Daily Email Check

Quickly check important unread emails every morning and filter out emails from key contacts (such as the boss and important customers).

Email Search and Organization

Need to find emails with a specific subject or content, such as searching for previous meeting minutes or project documents.

Quick Email Reply

When receiving customer inquiries or colleague questions, quickly view the original email and compose a reply.

Batch Email Management

Clean up the inbox by deleting spam emails or archiving old emails.

Frequently Asked Questions

Do I need programming knowledge to use it?

Which email services are supported?

Is my email password secure?

Can I send attachments?

What should I do if the connection fails?

Does it support multiple email accounts?

Related Resources

GitHub Repository

Project source code, issue feedback, and contribution guidelines.

NPM Package Page

Official npm package information and installation instructions.

Gmail App Password Guide

How to create a Gmail app-specific password (recommended).

Model Context Protocol Official Website

Official documentation and specifications for the MCP protocol.

🚀 MCP Mail Server

A Model Context Protocol server for IMAP/SMTP email operations with Claude, Cursor, and other AI assistants.

NPM Version

Language: English | 中文

✨ Features

IMAP Operations: Search, read, and manage emails across mailboxes
SMTP Support: Send emails with HTML/text content and attachments
Secure Configuration: Environment-based setup with TLS/SSL support
AI-Friendly: Natural language commands for email operations
Auto Connection Management: Automatic IMAP/SMTP connection handling
Multi-Mailbox Support: Access INBOX, Sent, and custom folders

🚀 Quick Start

Install: npm install -g mcp-mail-server
Configure environment variables (see Configuration)
Add to your MCP client configuration
Use natural language: "Show me unread emails from today"

📦 Installation

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["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": "your-email@domain.com",
        "EMAIL_PASS": "your-password"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["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": "your-email@domain.com",
        "EMAIL_PASS": "your-password"
      }
    }
  }
}

Other MCP Clients

For global installation:

npm install -g mcp-mail-server

Then configure with:

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "mcp-mail-server"
    }
  }
}

📚 Available Tools

Property	Details
`connect_all`	Connect to both IMAP and SMTP servers
`get_connection_status`	Check connection status and server info
`disconnect_all`	Disconnect from all servers
`open_mailbox`	Open specific mailbox/folder
`list_mailboxes`	List available mail folders
`search_messages`	Search emails with IMAP criteria
`search_by_sender`	Find emails from specific sender
`search_by_subject`	Search by subject keywords
`search_by_body`	Search message content
`search_since_date`	Find emails since date
`search_unreplied_from_sender`	Find unreplied emails from specific sender
`search_larger_than`	Find emails by size
`get_message`	Retrieve email by UID
`get_messages`	Retrieve multiple emails
`delete_message`	Delete email by UID
`get_unseen_messages`	Get all unread emails
`get_recent_messages`	Get recent emails
`send_email`	Send email via SMTP
`reply_to_email`	Reply to specific email

Detailed Tool Parameters

Connection Management

connect_all: No parameters required
get_connection_status: No parameters required
disconnect_all: No parameters required

Mailbox Operations

open_mailbox: mailboxName (string, default: "INBOX"), readOnly (boolean)
list_mailboxes: No parameters required

Search Operations

search_messages: criteria (array, IMAP search criteria)
search_by_sender: sender (string, email address)
search_by_subject: subject (string, keywords)
search_by_body: text (string, search text)
search_since_date: date (string, date format)
search_unreplied_from_sender: sender (string, email address), startDate (string, optional), endDate (string, optional)
search_larger_than: size (number, bytes)

Message Operations

get_message: uid (number), markSeen (boolean, optional)
get_messages: uids (array), markSeen (boolean, optional)
delete_message: uid (number)

Email Sending

send_email: to (string), subject (string), text (string, optional), html (string, optional), cc (string, optional), bcc (string, optional)
reply_to_email: originalUid (number), text (string), html (string, optional), replyToAll (boolean, optional), includeOriginal (boolean, optional)

💻 Usage Examples

Basic Usage

Use natural language commands with your AI assistant:

"Connect to my email servers"
"Show me all unread emails"
"Search for emails from boss@company.com"
"Send an email to team@company.com about the meeting"
"Reply to email with UID 123"

Advanced Usage

"Find emails with 'urgent' in the subject from last week"
"Show me unreplied emails from boss@company.com"
"Show me large emails over 5MB"
"Get all emails from the Sales folder"

Email Management

"Delete the email with UID 123"
"Mark recent emails as read"
"List all my email folders"

📚 Configuration

Environment Variables

⚠️ Important Note

All variables are required

Property	Details	Example
`IMAP_HOST`	IMAP server address	`imap.gmail.com`
`IMAP_PORT`	IMAP port number	`993`
`IMAP_SECURE`	Enable TLS	`true`
`SMTP_HOST`	SMTP server address	`smtp.gmail.com`
`SMTP_PORT`	SMTP port number	`465`
`SMTP_SECURE`	Enable SSL	`true`
`EMAIL_USER`	Email username	`your-email@gmail.com`
`EMAIL_PASS`	Email password/app password	`your-app-password`

Common Email Providers

Gmail Configuration

IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_SECURE=true
SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
SMTP_SECURE=true
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-password

⚠️ Important Note

Use App Passwords instead of your regular password.

Outlook/Hotmail Configuration

IMAP_HOST=outlook.office365.com
IMAP_PORT=993
IMAP_SECURE=true
SMTP_HOST=smtp.office365.com
SMTP_PORT=587
SMTP_SECURE=true
EMAIL_USER=your-email@outlook.com
EMAIL_PASS=your-password

Security Notes

⚠️ Important Note

Use App Passwords: Enable 2FA and use app-specific passwords when available

TLS/SSL Required: Always use secure connections (IMAP_SECURE=true, SMTP_SECURE=true)

Environment Variables: Never hardcode credentials in configuration files

🔧 Development

Local Development Setup

Clone the repository:

git clone https://github.com/yunfeizhu/mcp-mail-server.git
cd mcp-mail-server

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```

Set environment variables:

export IMAP_HOST=your-imap-server.com
export IMAP_PORT=993
export IMAP_SECURE=true
export SMTP_HOST=your-smtp-server.com
export SMTP_PORT=465
export SMTP_SECURE=true
export EMAIL_USER=your-email@domain.com
export EMAIL_PASS=your-password