Mcp Mail Server

Language: English | 中文

A Model Context Protocol (MCP) server that provides email capabilities through IMAP and SMTP protocols. This server enables LLMs to search, read, manage, and send emails on behalf of users.

Features

• Read/search/delete emails via IMAP

• Send and reply to emails via SMTP

• Read and export email attachments to local files

• Multi-mailbox support (INBOX, Sent, custom folders)

• Automatic IMAP/SMTP connection management

• Secure TLS/SSL connections

Installation

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "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"
      }
    }
  }
}

Run the following command in your terminal:

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

For more details, see the Claude Code MCP documentation.

For quick installation, click the install button below:

For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON).

Optionally, you can add it to a file called .vscode/mcp.json in your workspace. This will allow you to share the configuration with others.

Note that the mcp key is needed when using the mcp.json file.

{
  "mcp": {
    "servers": {
      "mcp-mail-server": {
        "command": "npx",
        "args": ["-y", "mcp-mail-server"],
        "env": {
          "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"
        }
      }
    }
  }
}

For more details about MCP configuration in VS Code, see the official VS Code MCP documentation.

Add to your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "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"
      }
    }
  }
}

Add to your Windsurf MCP configuration file (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "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"
      }
    }
  }
}

Open Cline settings in VS Code, navigate to MCP Servers, click Configure MCP Servers, and add:

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "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"
      }
    }
  }
}

Open Cherry Studio settings, navigate to MCP Servers, click Add Server, select type as STDIO, then fill in:

• Command: npx

• Args: -y mcp-mail-server

• Env Variables: Add all required environment variables (see Configuration)

Most MCP clients follow a similar JSON configuration pattern. The standard mcpServers config block works across nearly all clients:

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "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"
      }
    }
  }
}

Just place it in the MCP configuration file for your specific client. Refer to your client's documentation for the exact file location.

Alternatively, install globally and use mcp-mail-server as the command directly:

npm install -g mcp-mail-server

Related MCP server: MCP Advanced Reasoning Server

Tools

Connection Management

Mailbox Management

Email Search

Email Reading

Attachment fields in message objects: filename, contentType, size, contentBase64 (only when includeAttachmentContent=true and within size limit), contentTruncated (true when exceeds attachmentMaxBytes)

Attachment & Message Management

Sending & Replying

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

• "Send an email to

• "Reply to email with UID 123"

Advanced Searches

• "Find emails with 'urgent' in the subject from last week"

• "Show me unreplied emails from

• "Show me large emails over 5MB"

• "Get all emails from the Sales folder"

Attachment Operations

• "Get message 123 with attachment content included"

• "Get messages 101 and 102 without attachment content"

• "Export the first attachment of message 123 to /tmp/report.pdf"

• "Export attachment named invoice.pdf from message 123 to /tmp/invoice.pdf"

Email Management

• "Delete the email with UID 123"

• "Mark recent emails as read"

• "List all my email folders"

Configuration

Environment Variables

All environment variables are required:

Provider-Specific Setup

IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_SECURE=true
SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
SMTP_SECURE=true

IMAP_HOST=outlook.office365.com
IMAP_PORT=993
IMAP_SECURE=true
SMTP_HOST=smtp.office365.com
SMTP_PORT=587
SMTP_SECURE=true

IMAP_HOST=imap.mail.yahoo.com
IMAP_PORT=993
IMAP_SECURE=true
SMTP_HOST=smtp.mail.yahoo.com
SMTP_PORT=465
SMTP_SECURE=true

Security Best Practices

• Use App Passwords: Always use app-specific passwords instead of your main password

• Enable 2FA: Enable two-factor authentication on your email account

• Use TLS/SSL: Always set IMAP_SECURE=true and SMTP_SECURE=true

• Environment Variables Only: Never hardcode credentials in configuration files

Debugging

You can use the MCP Inspector to debug the server:

npx @modelcontextprotocol/inspector npx mcp-mail-server

Set the required environment variables in the Inspector's environment configuration panel before connecting.

Development

1. Clone the repository:

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

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. Run tests:

   npm test

Contributing

Contributions are welcome! Whether you want to add new tools, enhance existing functionality, or improve documentation — pull requests are appreciated.

For examples of other MCP servers and implementation patterns, see: https://github.com/modelcontextprotocol/servers

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.