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 MCP (Model Context Protocol) 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 bulk 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>Feature Highlights</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**: Intelligently identifies attachment types and supports previewing different types of attachments, such as text and images
- **Secure and Reliable**: 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 website](https://nodejs.org/)
- Download and install the LTS (Long-Term Support) version
- Select default options during installation, which will install both Node.js and npm
2. Verify installation
- After installation, open the command prompt (CMD) or PowerShell
- Enter the following commands to confirm successful installation:
```bash
node --version
npm --version
```
- If version numbers are displayed, it means the installation is successful
3. Install Git (if not installed)
- Visit the [Git 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 website](https://www.python.org/downloads/)
- Download and install Python 3.11 or higher
- **Important**: Make sure to select "Add Python to PATH" 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 based on 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\\YourUsername\\.cursor\\mcp.json`
- Note: Replace `YourUsername` with your actual Windows username
2. Add or modify the configuration as follows:
```json
{
"mcpServers": {
"mail-mcp": {
"command": "pythonw",
"args": [
"C:/Users/YourUsername/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 `YourUsername` with your actual Windows username
> - Ensure the path correctly points to your cloned or extracted project directory
> - 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/YourUsername/.cursor/mcp.json`
- Note: Replace `YourUsername` with your actual macOS username
2. Add or modify the configuration as follows:
```json
{
"mcpServers": {
"mail-mcp": {
"command": "pythonw",
"args": [
"/Users/YourUsername/mcp-mail/bridging_mail_mcp.py"
]
}
}
}
```
> ⚠️ **Please note**:
> - Replace `YourUsername` with your actual macOS username
> - Ensure the path correctly points to your cloned or extracted project directory
> - 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/YourUsername/.cursor/mcp.json`
- Note: Replace `YourUsername` with your actual Linux username
2. Add or modify the configuration as follows:
```json
{
"mcpServers": {
"mail-mcp": {
"command": "pythonw",
"args": [
"/home/YourUsername/mcp-mail/bridging_mail_mcp.py"
]
}
}
}
```
> ⚠️ **Please note**:
> - Replace `YourUsername` with your actual Linux username
> - Ensure the path correctly points to your cloned or extracted project directory
> - 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 start using it.
<details>
<summary>Usage Examples (click to expand)</summary>
You can ask AI to perform the following operations:
- "List my email folders"
- "Show 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 email 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 to retrieve 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, allowing 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 ⭐️ (｡♥‿♥｡)
