mcp-mail-server

v1.2.0

Published

8 days ago

MCP server for IMAP/SMTP email access with environment-based configuration

0High
0Medium
0Low

zhuyunfei

mcp imap smtp email mail server cursor claude model-context-protocol

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
Attachment Management: View attachment metadata and save attachments to local files
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": ["-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"
      }
    }
  }
}

Add to your Cursor MCP settings:

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

Add using the claude mcp add command:

claude mcp add mcp-mail-server \
  -e IMAP_HOST=your-imap-server.com \
  -e IMAP_PORT=993 \
  -e IMAP_SECURE=true \
  -e SMTP_HOST=your-smtp-server.com \
  -e SMTP_PORT=465 \
  -e SMTP_SECURE=true \
  -e [email protected] \
  -e EMAIL_PASS=your-password \
  -- npx -y mcp-mail-server

Or manually add to .claude/settings.json:

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

Add to codex.json in your project root:

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

Other MCP clients can be configured similarly. The core configuration is:

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

Refer to your specific client's documentation for the appropriate configuration file location.

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 | | get_message_count | Get total message count in current mailbox | | get_unseen_messages | Get all unread emails | | get_recent_messages | Get recent emails | | search_by_sender | Find emails from specific sender | | search_by_subject | Search by subject keywords | | search_by_recipient | Find emails sent to specific recipient | | search_by_body | Search message body content | | search_since_date | Find emails since date | | search_unread_from_sender | Find unread emails from specific sender | | search_unreplied_from_sender | Find unreplied emails from specific sender | | search_with_keyword | Search emails by keyword/flag | | search_all_messages | Search all messages with optional date range and limit | | get_message | Retrieve email by UID | | get_messages | Retrieve multiple emails | | delete_message | Delete email by UID | | send_email | Send email via SMTP (with optional attachments) | | reply_to_email | Reply to specific email | | get_attachments | Get attachment metadata for an email | | save_attachment | Download and save attachments to local files |

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_by_sender: sender (string, email address), startDate (string, optional), endDate (string, optional)
search_by_subject: subject (string, keywords), startDate (string, optional), endDate (string, optional)
search_by_recipient: recipient (string, email address), startDate (string, optional), endDate (string, optional)
search_by_body: text (string, search text), startDate (string, optional), endDate (string, optional)
search_since_date: date (string, date format)
search_unread_from_sender: sender (string, email address), startDate (string, optional), endDate (string, optional)
search_unreplied_from_sender: sender (string, email address), startDate (string, optional), endDate (string, optional), limit (number, optional)
search_with_keyword: keyword (string, keyword), startDate (string, optional), endDate (string, optional)
search_all_messages: startDate (string, optional), endDate (string, optional), limit (number, optional, default: 50)

Message Operations

get_message_count: No parameters required
get_unseen_messages: No parameters required
get_recent_messages: No parameters required
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), attachments (string[], optional, absolute file paths)
reply_to_email: originalUid (number), text (string), html (string, optional), replyToAll (boolean, optional), includeOriginal (boolean, optional)

Attachment Operations

get_attachments: uid (number) — Returns metadata: filename, contentType, size, index
save_attachment: uid (number), savePath (string, absolute path), attachmentIndex (number, optional, 0-based), returnBase64 (boolean, optional, default: false)

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 [email protected]"
"Send an email to [email protected] 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 [email protected]"
"Search emails sent to [email protected]"
"Get all emails from the Sales folder"
"Show unread emails from [email protected]"
"Show me all emails from the last 7 days"
"List all messages, limit to 20"

Email Management

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

Attachment Operations

"Show me the attachments of email UID 456"
"Save all attachments from email UID 456 to D:/Downloads"
"Download the first attachment from email UID 789"
"Send an email to [email protected] with attachment D:/report.pdf"

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 | [email protected] | | 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 protected]
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 protected]
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 protected]
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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

MCP Mail Server

Features

Quick Start

Installation

Available Tools

Connection Management

Mailbox Operations

Search Operations

Message Operations

Email Sending

Attachment Operations

Usage Examples

Basic Operations

Advanced Searches

Email Management

Attachment Operations

Configuration

Environment Variables

Common Email Providers

Security Notes

Development

Contributing

License