Content
# Email MCP Server
An email server based on Model Context Protocol (MCP) that allows AI to send, read, search, delete, and reply to emails. Supports both SMTP and Gmail API methods, compatible with common email services such as QQ Mail, 163 Mail, and Gmail.
## 🚀 Features
- ✉️ **Send Email** - Supports HTML/plain text format, attachment function
- 📥 **Read Email** - Read emails from inbox or specified folder
- 🔍 **Search Email** - Search emails by keywords
- 🗑️ **Delete Email** - Delete specified email
- ↩️ **Reply Email** - Supports reply and reply all
## 📦 Installation
```bash
npm install
npm run build
```
Or quick install:
```bash
npm run quick-setup
```
## ⚙️ Configuration
1. Copy environment variable template:
```bash
cp env.example .env
```
2. Edit the `.env` file and select an email provider:
### Option 1: Use QQ Mail (Recommended)
```env
EMAIL_PROVIDER=smtp
SMTP_HOST=smtp.qq.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@qq.com
SMTP_PASS=your-authorization-code
DEFAULT_FROM_EMAIL=your-email@qq.com
```
**QQ Mail Setup Steps:**
1. Log in to QQ Mail → Settings → Account
2. Enable SMTP service
3. Generate an authorization code (not QQ password)
4. Enter the authorization code into `SMTP_PASS`
### Option 2: Use 163 Mail
```env
EMAIL_PROVIDER=smtp
SMTP_HOST=smtp.163.com
SMTP_PORT=994
SMTP_SECURE=true
SMTP_USER=your-email@163.com
SMTP_PASS=your-authorization-code
DEFAULT_FROM_EMAIL=your-email@163.com
```
### Option 3: Use Gmail
```env
EMAIL_PROVIDER=smtp
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
DEFAULT_FROM_EMAIL=your-email@gmail.com
```
### Option 4: Use Gmail API
```env
EMAIL_PROVIDER=gmail
GMAIL_CLIENT_ID=your-gmail-client-id
GMAIL_CLIENT_SECRET=your-gmail-client-secret
GMAIL_REFRESH_TOKEN=your-gmail-refresh-token
DEFAULT_FROM_EMAIL=your-email@gmail.com
```
## 🔧 Usage
### Direct Start
```bash
npm run start
```
### Debug with SuperGateway (Recommended)
```bash
npm run start-gateway
```
Service will start at http://localhost:3200
### Configure in Cline
```json
{
"mcpServers": {
"email-mcp": {
"url": "http://localhost:3200/sse",
"type": "sse",
"disabled": false,
"autoApprove": [
"send_email",
"read_emails",
"search_emails",
"delete_email",
"reply_email"
]
}
}
}
```
### Development Mode
```bash
npm run dev
```
## 🛠️ Available Tools
### 1. send_email
Send email to the specified recipient
**Parameters:**
- `to` (required): Recipient email address
- `subject` (required): Email subject
- `body` (required): Email content
- `from` (optional): Sender email address
- `html` (optional): Whether it is in HTML format
- `attachments` (optional): Array of attachments
**Example:**
```json
{
"to": "recipient@qq.com",
"subject": "Greetings from AI",
"body": "This is a test email sent by an AI assistant.",
"html": false
}
```
### 2. read_emails
Read emails from inbox or specified folder
**Parameters:**
- `limit` (optional): Email quantity limit (default: 10)
- `folder` (optional): Email folder (default: "INBOX")
- `unreadOnly` (optional): Read only unread emails (default: false)
### 3. search_emails
Search emails
**Parameters:**
- `query` (required): Search keywords
- `limit` (optional): Result quantity limit (default: 10)
- `folder` (optional): Search folder (default: "INBOX")
### 4. delete_email
Delete email
**Parameters:**
- `messageId` (required): ID of the email to be deleted
### 5. reply_email
Reply to email
**Parameters:**
- `messageId` (required): Original email ID
- `body` (required): Reply content
- `replyAll` (optional): Whether to reply all (default: false)
- `html` (optional): Whether it is in HTML format (default: false)
## 🔐 Supported Email Services
| Email Service | SMTP Server | Port | Secure Connection | Description |
|---------------|-------------|------|-------------------|-------------|
| QQ Mail | smtp.qq.com | 587 | false | Requires enabling SMTP service and obtaining authorization code |
| 163 Mail | smtp.163.com | 994 | true | Requires enabling SMTP service and obtaining authorization code |
| Gmail | smtp.gmail.com | 587 | false | Requires enabling two-step verification and generating an app password |
| Outlook | smtp-mail.outlook.com | 587 | false | Requires enabling SMTP authentication |
## 🐛 Troubleshooting
### Common Issues
1. **QQ Mail Authentication Failed**
- Ensure SMTP service is enabled
- Use authorization code instead of QQ password
- Check if SMTP settings are correct
2. **163 Mail Authentication Failed**
- Ensure SMTP service is enabled
- Use client authorization password
- Note that port 994 is used and SSL is enabled
3. **Gmail Authentication Failed**
- Ensure "App Password" is enabled
- Enable two-step verification
- Check if SMTP settings are correct
4. **Gmail API Error**
- Ensure OAuth token is valid
- Check API quota and permissions
5. **TypeScript Compilation Error**
- Run `npm install` to ensure dependencies are fully installed
- Check Node.js version (recommended v18+)
## 🔗 Related Links
- [Model Context Protocol](https://github.com/anthropics/mcp)
- [SuperGateway](https://supergateway.ai)
- [Gmail API Documentation](https://developers.google.com/gmail/api)
- [QQ Mail SMTP Settings](https://service.mail.qq.com/cgi-bin/help?subtype=1&&id=28&&no=1001256)
## 📄 License
ISC License
