playbooks
Learn Cursor Rules Windsurf Rules MCPs Modes
Log in

Email (IMAP/SMTP) MCP server

Provides IMAP/SMTP email access for reading messages and sending emails with secure connection support and environment-based credential management.
Back to servers
Setup instructions
Provider
Euan Zhu
Release date
Jul 31, 2025
Language
Go
Stats
5 stars
View on GitHub

MCP Mail Server is a Model Context Protocol server that enables AI assistants like Claude and Cursor to perform IMAP/SMTP email operations. It allows you to search, read, and manage emails, as well as send emails with content and attachments through natural language commands.

Installation

Using NPM

You can install the MCP Mail Server globally using npm:

npm install -g mcp-mail-server

Client Configuration

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": "[email protected]",
        "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": "[email protected]",
        "EMAIL_PASS": "your-password"
      }
    }
  }
}

Other MCP Clients

For global installation:

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

Configuration

Environment Variables

All of the following 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

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 protected]
EMAIL_PASS=your-app-password

Note: Use App Passwords instead of your regular password when using Gmail.

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

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

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 [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]"
  • "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"

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "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":"[email protected]","EMAIL_PASS":"your-password"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "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": "[email protected]",
                "EMAIL_PASS": "your-password"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "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": "[email protected]",
                "EMAIL_PASS": "your-password"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect

Want to 10x your AI skills?

Get a free account and learn to code + market your apps using AI (with or without vibes!).

Nah, maybe later