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

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

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

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

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

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

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

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

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

Email (IMAP/SMTP)