Content
# Tool List
[](https://opensource.org/licenses/ISC)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://github.com/shuakami/mcp-mail)
[](https://smithery.ai/server/@shuakami/mcp-mail)
[English Version (README-EN.md)](README-EN.md)
## What is this
This is a mail tool based on the Model Context Protocol (MCP) that allows AI models to access email services through standardized interfaces.
In simple terms, it enables AI assistants to perform various email operations, such as sending emails, reading inboxes, and handling attachments, without requiring users to manually input complex API calls or switch to email clients.
<details>
<summary><b>Supported Features</b> (click to expand)</summary>
- **Email Sending**: Plain text emails, HTML emails, emails with attachments, and mass emails
- **Email Receiving and Querying**: Get folder lists, list emails, advanced search, and get email details
- **Email Management**: Mark as read/unread, delete emails, and move emails
- **Attachment Management**: View attachment lists, download attachments, and view attachment content
- **Contact Management**: Get contact lists and search contacts
</details>
<details>
<summary><b>Functional Characteristics</b> (click to expand)</summary>
Here are some core features of the Mail MCP tool:
- **Advanced Search Function**: Supports complex condition searches with multiple folders, keywords, date ranges, senders, and recipients
- **Intelligent Contact Management**: Automatically extracts contact information from email history, including contact frequency analysis
- **Content Range Control**: Allows segmented viewing of large emails to avoid loading too much content
- **Multiple Email Formats**: Supports sending and displaying plain text and HTML format emails
- **Attachment Handling Capability**: Intelligently recognizes attachment types and supports previewing different types of attachments, such as text and images
- **Security and Reliability**: Locally processes all email operations without forwarding sensitive information through third-party servers
Through simple natural language instructions, AI can help you complete all the above operations without manually writing API calls or performing complex operations in email clients.
</details>
## Quick Start
### 0. Environment Preparation
<details>
<summary>If you haven't used Node.js before (click to expand)</summary>
1. Install Node.js and npm
- Visit the [Node.js official website](https://nodejs.org/)
- Download and install the LTS (Long Term Support) version
- Select default options during installation, which will install Node.js and npm simultaneously
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 is successful
3. Install Git (if not installed)
- Visit the [Git official website](https://git-scm.com/)
- Download and install Git
- Use default options during installation
4. Install Python 3.11 or higher (required)
- Visit the [Python official website](https://www.python.org/downloads/)
- Download and install Python 3.11 or higher
- **Important**: Select the "Add Python to PATH" option during installation
- Restart your computer after installation to ensure environment variables take effect
</details>
### Installing via Smithery
To install Mail MCP Tool for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@shuakami/mcp-mail):
```bash
npx -y @smithery/cli install @shuakami/mcp-mail --client claude
```
### 1. Clone and Install
```bash
git clone https://github.com/shuakami/mcp-mail.git
cd mcp-mail
npm install
npm run build
```
### 2. Build the Project
```bash
npm run build
```
### 3. Add to Cursor MCP Configuration
Follow the steps below to configure MCP according to your operating system:
<details>
<summary><b>Windows Configuration</b> (click to expand)</summary>
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": "pythonw",
"args": [
"C:/Users/Your Username/mcp-mail/bridging_mail_mcp.py"
],
"env": {
"SMTP_HOST": "smtp.qq.com",
"SMTP_PORT": "465",
"SMTP_SECURE": "true",
"SMTP_USER": "your.email@qq.com",
"SMTP_PASS": "your-app-specific-password",
"IMAP_HOST": "imap.qq.com",
"IMAP_PORT": "993",
"IMAP_SECURE": "true",
"IMAP_USER": "your.email@qq.com",
"IMAP_PASS": "your-app-specific-password",
"DEFAULT_FROM_NAME": "Your Name",
"DEFAULT_FROM_EMAIL": "your.email@qq.com"
}
}
}
}
```
> ⚠️ **Please note**:
> - Replace `Your Username` with your Windows username
> - Ensure the path correctly points to the directory 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 MCP to malfunction
</details>
<details>
<summary><b>macOS Configuration</b> (click to expand)</summary>
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": "pythonw",
"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 the directory 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 MCP to malfunction
</details>
<details>
<summary><b>Linux Configuration</b> (click to expand)</summary>
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": "pythonw",
"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 the directory 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 MCP to malfunction
</details>
### 4. Start the Service
After configuring, restart the Cursor editor, and it will automatically start the MCP service. You can then begin using it.
<details>
<summary>Usage Examples (click to expand)</summary>
You can ask AI to perform the following operations:
- "List my mailbox folders"
- "Display the latest 5 emails in the 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 an email"
</details>
## How it Works
<details>
<summary>Technical Implementation Details (click to expand)</summary>
This tool is 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 underlying mail clients and **Zod** for request validation and type checking.
Main technical components include:
- **SMTP Client**: Responsible for all email sending functions, supporting HTML content and attachments
- **IMAP Client**: Connects to email servers, retrieves email lists, details, and attachments
- **Email Parser**: Uses **mailparser** to parse complex email formats
- **Content Processing**: Intelligently handles HTML and plain text content, supporting segmented loading of large emails
- **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 presentation in a human-readable format, enabling AI models to easily understand the content structure of emails.
</details>
## License
ISC
---
If this project helps you, feel free to give it a Star ⭐️ (｡♥‿♥｡)
