MCP Mail Server

NPM Version

Language: English | 中文

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

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

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"
      }
    }
  }
}

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"
      }
    }
  }
}

For global installation:

npm install -g mcp-mail-server

Then configure with:

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

Available Tools

Tool	Description
`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

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

Use natural language commands with your AI assistant:

Basic Operations

"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 Searches

"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

⚠️ All variables are required

Variable	Description	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

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

Note: Use App Passwords instead of your regular password.

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

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

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
Run the server:
npm start

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.

Package Information:

Package: mcp-mail-server
Node.js: ≥18.0.0
Repository: GitHub
Issues: Report bugs

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A Model Context Protocol server that enables email operations through POP3 and SMTP protocols in Cursor AI, allowing users to send, receive, list, and manage emails using natural language commands.

Related MCP Servers

Cursor DB MCP Server
jbdamask
-
security
F
license
-
quality
A Model Context Protocol server that enables AI assistants to explore and interact with Cursor IDE's SQLite databases, providing access to project data, chat history, and composer information.
Last updated -
21
Python
MCP Advanced Reasoning Server
AzDeltaQQ
A
security
F
license
A
quality
A Model Context Protocol server that enhances Claude in Cursor AI with advanced reasoning capabilities including Monte Carlo Tree Search, Beam Search, R1 Transformer, and Hybrid Reasoning methods.
Last updated -
8
13
TypeScript
TaskMaster
mingolladaniele
-
security
F
license
-
quality
A Model Context Protocol server that enables Cursor AI assistants to interact with Todoist tasks directly from the coding environment, supporting advanced task filtering and rich formatting.
Last updated -
39
Python
IMAP MCP Server
non-dirty
-
security
F
license
-
quality
A Model Context Protocol server that enables AI assistants to access and manage email through IMAP, supporting browsing, searching, reading, and organizing emails while learning user preferences over time.
Last updated -
16
Python

View all related MCP servers