https://github.com/shuakami/mcp-mail
📧 MCP Mail Tool - AI-powered email management tool | 基于 MCP 的智能邮件管理工具
https://github.com/shuakami/mcp-mail
ai ai-tools anthropic automation chatgpt claude cursor developer-tools email email-automation email-client imap mail-client mail-service mcp nodejs openai productivity smtp typescript
Last synced: 7 months ago
JSON representation
📧 MCP Mail Tool - AI-powered email management tool | 基于 MCP 的智能邮件管理工具
- Host: GitHub
- URL: https://github.com/shuakami/mcp-mail
- Owner: shuakami
- Created: 2025-03-20T06:17:17.000Z (7 months ago)
- Default Branch: master
- Last Pushed: 2025-03-20T11:06:54.000Z (7 months ago)
- Last Synced: 2025-03-20T11:22:38.906Z (7 months ago)
- Topics: ai, ai-tools, anthropic, automation, chatgpt, claude, cursor, developer-tools, email, email-automation, email-client, imap, mail-client, mail-service, mcp, nodejs, openai, productivity, smtp, typescript
- Language: TypeScript
- Size: 44.9 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README-EN.md
- Changelog: changes.txt
Awesome Lists containing this project
README
# Mail MCP Tool
[](https://opensource.org/licenses/ISC)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://github.com/shuakami/mcp-mail)
[中文版 (README.md)](README.md)
## What is this
This is an email tool based on MCP (Model Context Protocol) that enables AI models to access email services through a standardized interface.
Simply put, it allows AI assistants to perform various email operations such as sending emails, reading inboxes, processing attachments, etc., without requiring users to manually input complex API calls or switch to an email client.
Supported Features (click to expand)
- **Email Sending**: Plain text emails, HTML emails, emails with attachments, bulk emails
- **Email Receiving and Querying**: Get folder list, list emails, advanced search, get email details
- **Email Management**: Mark as read/unread, delete emails, move emails
- **Attachment Management**: View attachment list, download attachments, view attachment content
- **Contact Management**: Get contact list, search contacts
Feature Highlights (click to expand)
Here are some core features of the Mail MCP tool:
- **Advanced Search Functionality**: Support for multi-folder, keyword, date range, sender, recipient, and other complex search conditions
- **Intelligent Contact Management**: Automatically extract contact information from email history, including contact frequency analysis
- **Content Range Control**: View large emails in segments to avoid loading too much content
- **Multiple Email Formats**: Support for sending and displaying plain text and HTML format emails
- **Attachment Processing Capability**: Intelligent identification of attachment types, support for previewing text, images, and other attachment types
- **Secure and Reliable**: Process all email operations locally, without forwarding sensitive information through third-party servers
Through simple natural language instructions, AI can help you complete all the above operations without having to manually write API calls or perform complex operations in an email client.
## Quick Start
### 0. Environment Preparation
If you have never used Node.js before (click to expand)
1. Install Node.js and npm
- Visit the [Node.js website](https://nodejs.org/)
- Download and install the LTS (Long Term Support) version
- Choose the default options during installation, which will install both Node.js and npm
2. Verify installation
- After installation, open Command Prompt (CMD) or PowerShell
- Enter the following commands to confirm successful installation:
```bash
node --version
npm --version
```
- If version numbers are displayed, the installation was successful
3. Install Git (if not already installed)
- Visit the [Git website](https://git-scm.com/)
- Download and install Git
- Use the default options during installation
4. Install Python 3.11 or higher (required)
- Visit the [Python website](https://www.python.org/downloads/)
- Download and install Python 3.11 or higher
- **Important**: You MUST check the "Add Python to PATH" option during installation
- **Restart your computer** after installation to ensure environment variables take effect
### 1. Clone and Install
```bash
git clone https://github.com/shuakami/mcp-mail.git
cd mcp-mail
npm install
```
### 2. Build the Project
```bash
npm run build
```
### 3. Configure Email Account
Email Configuration Steps (click to expand)
1. Create a configuration file
- In the project root directory, create a `mcp.json` file
2. Configure your email information
```json
{
"smtp": {
"host": "smtp.example.com",
"port": 465,
"secure": true,
"auth": {
"user": "your.email@example.com",
"pass": "your-password-or-app-password"
}
},
"imap": {
"host": "imap.example.com",
"port": 993,
"secure": true,
"auth": {
"user": "your.email@example.com",
"pass": "your-password-or-app-password"
}
},
"defaults": {
"fromName": "Your Name",
"fromEmail": "your.email@example.com"
}
}
```
3. Configuration references for common email service providers
**QQ Mail**
```json
{
"smtp": {
"host": "smtp.qq.com",
"port": 465,
"secure": true
},
"imap": {
"host": "imap.qq.com",
"port": 993,
"secure": true
}
}
```
**Gmail**
```json
{
"smtp": {
"host": "smtp.gmail.com",
"port": 465,
"secure": true
},
"imap": {
"host": "imap.gmail.com",
"port": 993,
"secure": true
}
}
```
**Outlook/Hotmail**
```json
{
"smtp": {
"host": "smtp-mail.outlook.com",
"port": 587,
"secure": false
},
"imap": {
"host": "outlook.office365.com",
"port": 993,
"secure": true
}
}
```
> ⚠️ **Security Tips**:
> - For services like Gmail and Outlook, use an [app-specific password](https://support.google.com/accounts/answer/185833) instead of your account password
> - For QQ Mail, you need to enable POP3/SMTP/IMAP services in QQ Mail settings and obtain an authorization code
> - Make sure your `mcp.json` file is not committed to a public code repository
### 4. Add to Cursor MCP Configuration
Follow these steps to configure MCP according to your operating system:
Windows Configuration (click to expand)
1. In Cursor, open or create the MCP configuration file: `C:\\Users\\your-username\\.cursor\\mcp.json`
- Note: Replace `your-username` with your Windows username
2. Add or modify the configuration as follows:
```json
{
"mcpServers": {
"mail-mcp": {
"command": "python",
"args": [
"C:/Users/your-username/mcp-mail/bridging_mail_mcp.py"
]
}
}
}
```
> ⚠️ **Please note**:
> - Replace `your-username` with your Windows username
> - Ensure the path correctly points to where you cloned or extracted the project
> - The path should reflect the actual location where you placed the project files
> - **Do not delete the cloned or extracted folder**, as this will cause the MCP to stop working
macOS Configuration (click to expand)
1. In Cursor, open or create the MCP configuration file: `/Users/your-username/.cursor/mcp.json`
- Note: Replace `your-username` with your macOS username
2. Add or modify the configuration as follows:
```json
{
"mcpServers": {
"mail-mcp": {
"command": "python3",
"args": [
"/Users/your-username/mcp-mail/bridging_mail_mcp.py"
]
}
}
}
```
> ⚠️ **Please note**:
> - Replace `your-username` with your macOS username
> - Ensure the path correctly points to where you cloned or extracted the project
> - The path should reflect the actual location where you placed the project files
> - **Do not delete the cloned or extracted folder**, as this will cause the MCP to stop working
Linux Configuration (click to expand)
1. In Cursor, open or create the MCP configuration file: `/home/your-username/.cursor/mcp.json`
- Note: Replace `your-username` with your Linux username
2. Add or modify the configuration as follows:
```json
{
"mcpServers": {
"mail-mcp": {
"command": "python3",
"args": [
"/home/your-username/mcp-mail/bridging_mail_mcp.py"
]
}
}
}
```
> ⚠️ **Please note**:
> - Replace `your-username` with your Linux username
> - Ensure the path correctly points to where you cloned or extracted the project
> - The path should reflect the actual location where you placed the project files
> - **Do not delete the cloned or extracted folder**, as this will cause the MCP to stop working
### 5. Start the Service
After configuration, restart the Cursor editor, which will automatically start the MCP service. Then you can start using it.
Usage Examples (click to expand)
You can ask the AI to perform the following operations:
- "List my email folders"
- "Show the latest 5 emails in my inbox"
- "Send an email with the subject 'Test Email' to example@example.com"
- "Search for emails containing the keyword 'invoice'"
- "View the details of the email with UID 1234"
- "Download attachments from the email"
## How It Works
Technical Implementation Details (click to expand)
This tool is implemented based on the **MCP (Model Context Protocol)** standard, serving as a bridge between AI models and email services. It uses **nodemailer** and **node-imap** as the underlying email clients, and **Zod** for request validation and type checking.
The main technical components include:
- **SMTP Client**: Responsible for all email sending functions, supporting HTML content and attachments
- **IMAP Client**: Responsible for connecting to email servers, retrieving email lists, details, and attachments
- **Email Parser**: Uses **mailparser** to parse complex email formats
- **Content Processing**: Intelligently processes HTML and plain text content, and supports loading large emails in segments
- **Contact Extraction**: Automatically extracts and organizes contact information from email history
Each email operation is encapsulated as a standardized MCP tool, receiving structured parameters and returning formatted results. All data is processed to ensure it is presented in a human-readable format, making it easy for AI models to understand the content structure of emails.
## License
ISC
---
If this project helps you, please consider giving it a Star ⭐️ (｡♥‿♥｡)