home / mcp / email mcp server

Email MCP Server

一个基于Model Context Protocol (MCP) 的邮件服务器，让AI可以发送、读取、搜索、删除和回复邮件。支持SMTP和Gmail API两种方式，兼容QQ邮箱、163邮箱、Gmail等常见邮箱服务。

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "guangxiangdebizi-email-mcp": {
      "url": "http://localhost:3200/sse",
      "headers": {
        "SMTP_HOST": "smtp.qq.com",
        "SMTP_PASS": "YOUR_AUTH_CODE",
        "SMTP_PORT": "587",
        "SMTP_USER": "[email protected]",
        "SMTP_SECURE": "false",
        "EMAIL_PROVIDER": "smtp",
        "GMAIL_CLIENT_ID": "YOUR_CLIENT_ID",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "GMAIL_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "GMAIL_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN"
      }
    }
  }
}

You can run an MCP-based email server that lets you send, read, search, delete, and reply to emails using either SMTP providers or the Gmail API. This server is designed to be controlled by MCP clients, enabling seamless email operations through a consistent interface.

How to use

Use an MCP client to interact with the Email MCP Server. You can perform core actions such as sending emails (with HTML or plain text and optional attachments), reading emails from the inbox or a specific folder, searching messages by keywords, deleting messages by ID, and replying to messages (with options to reply to the sender only or to all recipients). When configuring your client, you’ll target the MCP server’s endpoint and call the available tools: send_email, read_emails, search_emails, delete_email, and reply_email. Ensure the server is running and the MCP gateway is accessible at the configured URL.

How to install

Prerequisites you need before installation: Node.js (recommended v18+). You will also need a compatible MCP client to consume the server’s endpoints.

Steps to install and run the Email MCP Server locally:

1. Install dependencies and build the project.

2. Start the server in standard mode or via the gateway for debugging.

Configuration and runtime setup

Configure your email provider in the environment file that the server reads. You can choose between SMTP-based providers (QQ Mail, 163 Mail, Gmail) or Gmail API. Populate the appropriate environment variables as shown in the examples below.

# Example: SMTP with QQ Mail
EMAIL_PROVIDER=smtp
SMTP_HOST=smtp.qq.com
SMTP_PORT=587
SMTP_SECURE=false
[email protected]
SMTP_PASS=your-authorization-code
[email protected]
```
```env
# Example: SMTP with 163 Mail
EMAIL_PROVIDER=smtp
SMTP_HOST=smtp.163.com
SMTP_PORT=994
SMTP_SECURE=true
[email protected]
SMTP_PASS=your-authorization-code
[email protected]
```
```env
# Example: Gmail SMTP
EMAIL_PROVIDER=smtp
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
[email protected]
SMTP_PASS=your-app-password
[email protected]
```
```env
# Example: Gmail API
EMAIL_PROVIDER=gmail
GMAIL_CLIENT_ID=your-gmail-client-id
GMAIL_CLIENT_SECRET=your-gmail-client-secret
GMAIL_REFRESH_TOKEN=your-gmail-refresh-token
[email protected]
```"} ,{

MCP connection configuration

The MCP client can connect to the server using either a remote HTTP endpoint or a local runtime command. The following example shows an HTTP connection pointing to the server’s MCP stream (SSE) endpoint, followed by a local runtime configuration that starts the server via npm.

{
  "mcpServers": {
    "email_mcp": {
      "url": "http://localhost:3200/sse",
      "type": "http",
      "disabled": false,
      "autoApprove": [
        "send_email",
        "read_emails", 
        "search_emails",
        "delete_email",
        "reply_email"
      ]
    }
  }
}
```"} ,{

Developer/runtime commands

The server can also be started directly in a local development environment using npm. If you prefer a gateway for debugging, you can use the gateway mode as well.

npm run start
```

```
npm run start-gateway
```

```
npm run dev

Available tools and endpoints

The MCP server exposes the following tools for email operations. Each tool accepts a set of parameters as shown.

1) send_email
   - to, subject, body, from, html, attachments
2) read_emails
   - limit, folder, unreadOnly
3) search_emails
   - query, limit, folder
4) delete_email
   - messageId
5) reply_email
   - messageId, body, replyAll, html

Troubleshooting

If you encounter authentication or connection issues with SMTP providers, ensure you generated and used the appropriate app passwords or authorization codes, and that SMTP services are enabled. For Gmail API issues, verify OAuth tokens and API access permissions. If you run into TypeScript or dependency problems, reinstall dependencies and verify your Node.js version.

Notes and tips

Keep your environment variables secure and never expose your SMTP credentials in client configurations. When using Gmail, prefer app passwords or OAuth tokens and maintain proper scopes for reading and sending emails.

Available tools

send_email

Sends an email to a specified recipient with optional HTML content and attachments.

read_emails

Reads emails from the inbox or a specified folder with optional limits and unread filtering.

search_emails

Searches emails by a keyword in a specified folder with optional limit.

delete_email

Deletes a specified email by its messageId.

reply_email

Replies to a message or all recipients with optional HTML content.