Content
# Email MCP Server
A Python-based email MCP (Model Context Protocol) server that provides email sending capabilities for AI assistants.
## Features
- [OK] Supports QQ Mail and Gmail
- [OK] Multi-recipient support (To, Cc, Bcc)
- [OK] Local and remote attachment support
- [OK] Complete error handling and retry mechanism
- [OK] STDIO-based MCP protocol communication
- [OK] Automatic SMTP server configuration
- [OK] Email priority setting
- [OK] HTML and plain text email support
- [OK] **Interactive Email Confirmation**: Preview and confirm email content before sending
- [OK] **87.22% Test Coverage**, enterprise-level code quality
- [OK] **185 Test Cases**, 184 passed (100% execution pass rate)
- [OK] **Complete Type Annotations**, strictly checked by MyPy
## Quick Start
### Environment Requirements
- Python 3.14+
- uv package manager (recommended) or pip
### Installation
#### Method 1: Using uv (recommended)
1. Clone the project
```bash
git clone <repository-url>
cd email-mcp-server
```
2. Install dependencies and create a virtual environment
```bash
uv sync
```
3. Configure environment variables
```bash
cp .env.example .env
# Edit .env file and fill in your email credentials
```
4. Run the server
```bash
# Method 1: Using batch script (Windows)
start_server.bat
# Method 2: Using uv
uv run python -m email_mcp_server
```
#### Method 2: Using traditional pip
1. Clone the project
```bash
git clone <repository-url>
cd email-mcp-server
```
2. Create a virtual environment
```bash
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate
```
3. Install dependencies
```bash
pip install -e ".[dev]"
```
4. Configure environment variables
```bash
cp .env.example .env
# Edit .env file and fill in your email credentials
```
5. Run the server
```bash
# Method 1: Using batch script (Windows)
start_server.bat
# Method 2: Manual run
python -m email_mcp_server
```
## Configuration
### QQ Mail Configuration
1. Log in to QQ Mail
2. Go to Settings -> Account
3. Enable SMTP service
4. Obtain authorization code (not login password)
### Gmail Configuration
1. Log in to Google Account
2. Enable two-step verification
3. Generate app-specific password
4. Use app-specific password as EMAIL_PASSWORD
### Environment Variables
```env
EMAIL_ADDRESS=your_email@example.com
EMAIL_PASSWORD=your_password_or_auth_code
```
## MCP Client Configuration and Usage
This MCP server can be integrated with various AI clients through the stdio protocol to provide email sending capabilities for AI assistants.
### Claude Code Configuration
Configure MCP server in Claude Code:
1. **Open Claude Code settings**
2. **Add MCP server configuration**:
```json
{
"mcpServers": {
"email-mcp-server": {
"command": "uv",
"args": ["run", "python", "-m", "email_mcp_server"],
"cwd": "/path/to/email-mcp-server",
"env": {
"EMAIL_ADDRESS": "your_email@example.com",
"EMAIL_PASSWORD": "your_password_or_auth_code"
}
}
}
}
```
3. **Use in Claude Code**:
```bash
# Claude Code will automatically load MCP tools, you can directly use them in conversation:
"Please send a project progress email to team@company.com, subject is 'Weekly Progress Report', including attachment /path/to/report.pdf"
```
### Cursor Configuration
Configure MCP server in Cursor:
1. **Open Cursor settings** (`Ctrl/Cmd + ,`)
2. **Find MCP configuration section**
3. **Add server configuration**:
```json
{
"mcp": {
"servers": {
"email": {
"command": "uv",
"args": ["run", "python", "-m", "email_mcp_server"],
"cwd": "/path/to/email-mcp-server",
"env": {
"EMAIL_ADDRESS": "your_email@example.com",
"EMAIL_PASSWORD": "your_password_or_auth_code"
}
}
}
}
}
```
4. **Restart Cursor**
5. **Use in Cursor**:
```bash
# Use email function in Cursor AI chat:
"Please send an email to support@example.com, describing the software bug situation"
```
### VS Code + Copilot Configuration
Use VS Code MCP extension:
1. **Install MCP extension** (e.g., Model Context Protocol)
2. **Configure MCP server**:
```json
{
"mcp.servers": [
{
"name": "email-mcp-server",
"command": "uv",
"args": ["run", "python", "-m", "email_mcp_server"],
"cwd": "/path/to/email-mcp-server",
"environment": {
"EMAIL_ADDRESS": "your_email@example.com",
"EMAIL_PASSWORD": "your_password_or_auth_code"
}
}
]
}
```
### Other MCP Client Configurations
#### Direct Command Line Usage
```bash
# Run MCP server directly
cd /path/to/email-mcp-server
uv run python -m email_mcp_server
```
#### Docker Container Run
```dockerfile
# Dockerfile
FROM python:3.14-slim
WORKDIR /app
COPY . .
RUN pip install uv && uv sync
ENV EMAIL_ADDRESS=your_email@example.com
ENV EMAIL_PASSWORD=your_password_or_auth_code
CMD ["uv", "run", "python", "-m", "email_mcp_server"]
```
```bash
# Build and run
docker build -t email-mcp-server .
docker run --rm -it email-mcp-server
```
## Usage Examples
### Usage in Claude Code
```bash
# User conversation example:
"Please send a meeting reminder email to john@example.com, including:
- Meeting time: Tomorrow 3 PM
- Meeting location: Meeting Room A
- Meeting topic: Project progress discussion
- Attachment: /path/to/agenda.pdf"
# Claude will automatically call send_email tool to send email
```
### Usage in Cursor
```bash
# AI assistant conversation:
"Please verify if the email address user@domain.com is in a valid format"
# AI will automatically call validate_email tool to verify email format
```
### Available MCP Tools
1. **send_email** - Send email
- Supports multiple recipients (To, Cc, Bcc)
- Supports local and remote attachments
- Supports HTML and plain text content
- **Supports interactive confirmation**: Configurable confirmation before sending
2. **validate_email** - Verify email address format
3. **check_email_config** - Check email configuration
4. **get_supported_providers** - Get supported email provider information
### Basic Email Sending
```python
# Call through MCP client
send_email(
to=["recipient@example.com"],
subject="Test Email",
body="This is a test email",
attachments=["/path/to/file.pdf"]
)
```
### Remote Attachment
```python
send_email(
to=["recipient@example.com"],
subject="Email with remote attachment",
body="Email content",
attachments=["https://example.com/file.pdf"]
)
```
### [LOCK] Interactive Email Confirmation
Email MCP server supports interactive confirmation function, which allows previewing and confirming email content before sending:
#### Global Confirmation Configuration
Set global confirmation switch in `.env` file:
```env
# Enable global email confirmation
REQUIRE_CONFIRMATION=true
# Disable global email confirmation (default)
# REQUIRE_CONFIRMATION=false
```
#### Parameter-level Confirmation Control
Override global setting when sending email:
```python
# Force require confirmation (override global setting)
send_email(
to=["recipient@example.com"],
subject="Important Email",
body="Email content",
require_confirmation=True
)
# Skip confirmation (override global setting)
send_email(
to=["recipient@example.com"],
subject="Batch Notification",
body="Email content",
require_confirmation=False
)
```
#### Confirmation Process Example
When confirmation is enabled, the email sending process is as follows:
1. **Email Preview**: Display complete email information (recipients, subject, body, attachments, etc.)
2. **User Confirmation**: User can choose to confirm sending or cancel operation
3. **Execute Sending**: Confirm and immediately send email, cancel then terminate operation
#### Configuration Priority
Confirmation feature priority:
1. **Parameter-level setting** (`require_confirmation` parameter) - Highest priority
2. **Global environment variable** (`REQUIRE_CONFIRMATION`) - Medium priority
3. **Default setting** (`false`) - Lowest priority
> [LIGHTBULB] **Tip**: For detailed interactive confirmation configuration and usage, please refer to [Confirmation Function Guide](REQUIRE_CONFIRMATION_GUIDE.md)
## Development
### Code Quality Check
#### Using uv (recommended)
```bash
# Code format check
uv run ruff check src/
# Code format check and auto-fix
uv run ruff check --fix src/
# Code formatting
uv run ruff format src/
# Type check
uv run mypy src/
```
#### Using traditional way
```bash
# Activate virtual environment first
# Windows
.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate
# Code format check
ruff check src/
# Code format check and auto-fix
ruff check --fix src/
# Code formatting
ruff format src/
# Type check
mypy src/
```
### Testing
Our project has **87.22% test coverage**, including 185 test cases (184 passed, 1 skipped, 100% execution pass rate), ensuring code quality and functional reliability. Core features have reached production-ready standards.
#### Using uv (recommended)
```bash
# Run all tests
uv run pytest
# Run tests and generate coverage report
uv run pytest --cov=email_mcp_server --cov-report=term-missing
# Run specific module tests
uv run pytest tests/test_email_service.py # Email service test
uv run pytest tests/test_attachment_service.py # Attachment service test
uv run pytest tests/test_config.py # Configuration management test
uv run pytest tests/test_models.py # Data model test
```
#### Test Coverage Details
- **EmailService**: 97% coverage (152 statements, 4 uncovered)
- **Models**: 92% coverage (216 statements, 18 uncovered)
- **Main**: 98% coverage (40 statements, 1 uncovered)
- **AttachmentService**: 84% coverage (146 statements, 23 uncovered)
- **Exceptions**: 87% coverage (46 statements, 6 uncovered)
- **LoggingConfig**: 89% coverage (28 statements, 3 uncovered)
- **Config**: 89% coverage (65 statements, 7 uncovered)
- **EmailTools**: 61% coverage (93 statements, 36 uncovered)
- **Overall**: 87.22% coverage (790 statements, 101 uncovered, 100% execution pass rate)
#### Using traditional way
```bash
# Activate virtual environment first (commands same as above)
# Run all tests
pytest
# Run tests and generate coverage report
pytest --cov=email_mcp_server --cov-report=term-missing
```
## Project Structure
```
email-mcp-server/
├── src/email_mcp_server/ # Main source code
│ ├── __init__.py # Package initialization
│ ├── __main__.py # Module entry point
│ ├── main.py # Server main entry
│ ├── config.py # Configuration management (92% test coverage)
│ ├── email_service.py # Email service core (86% test coverage)
│ ├── email_tools.py # MCP tool registration
│ ├── attachment_service.py # Attachment processing service (77% test coverage)
│ ├── models.py # Data model (90% test coverage)
│ ├── exceptions.py # Custom exceptions
│ └── logging_config.py # Logging configuration
├── tests/ # Test files (87.2% coverage)
│ ├── test_data_factory.py # Test data factory
│ ├── mock_strategy.py # Mock strategy management
│ ├── test_config.py # Configuration management test (23 tests, 100% passed)
│ ├── test_models.py # Data model test (41 tests, 100% passed)
│ ├── test_email_service.py # Email service test (35 tests, 97.1% passed)
│ ├── test_attachment_service.py # Attachment service test (19 tests, 100% passed)
│ ├── test_email_tools.py # MCP tool test (9 tests, 100% passed)
│ ├── test_integration_real.py # Integration test (7 tests, 100% passed)
│ ├── test_logging_config.py # Logging configuration test (15 tests, 100% passed)
│ ├── test_main.py # Main program test (13 tests, 100% passed)
│ ├── test_require_confirmation.py # Confirmation function test (17 tests, 100% passed)
│ ├── conftest.py # pytest configuration
│ └── __init__.py # Test package initialization
├── docs/ # Documentation
├── .env.example # Environment variable template
├── .env # Actual environment variable configuration
├── start_server.bat # Windows startup script
├── start_server.sh # Linux/macOS startup script
├── pyproject.toml # Project configuration and dependencies
├── pytest.ini # pytest test configuration
├── mypy.ini # MyPy type check configuration
├── CLAUDE.md # Claude Code development guide
├── Virtual Environment Usage Guide.md # Virtual environment usage instructions
├── Test Plan.md # Project test plan and progress
└── README.md # Project description
```
## Complete Documentation
We provide comprehensive documentation to help you better use Email MCP Server:
### Documentation Center
- **[Documentation Center](docs/README.md)** - Navigation center for all documentation
### Quick Start
- **[Configuration Guide](docs/CONFIGURATION.md)** - Detailed configuration parameters and best practices
- **[MCP Client Configuration](docs/MCP_CLIENT_SETUP.md)** - Claude Code, Cursor, VS Code, etc. configuration
- **[Example Code](docs/EXAMPLES.md)** - Rich usage examples and actual scenarios
### Development Guide
- **[Development Guide](docs/DEVELOPMENT_GUIDE.md)** - Development environment setup and contribution guide
- **[Contribution Guide](CONTRIBUTING.md)** - How to participate in project development
- **[Testing Guide](docs/DEVELOPMENT_GUIDE.md#测试开发)** - Test writing and execution
### References
- **[API Documentation](docs/API.md)** - Complete API interface description
- **[Frequently Asked Questions](docs/FAQ.md)** - Frequently asked questions and answers
- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Problem diagnosis and solutions
- **[Change Log](CHANGELOG.md)** - Version update records
### Other Documents
- **[Confirmation Function Guide](REQUIRE_CONFIRMATION_GUIDE.md)** - require_confirmation function details
- **[Virtual Environment Guide](虚拟环境使用指南.md)** - uv and venv usage guide
- **[Test Plan](测试计划.md)** - Project test status and report
## Quick Navigation
| User Type | Recommended Reading | Link |
|---------|---------|------|
| **Beginner** | Installation and Configuration → Basic Usage | [Configuration Guide](docs/CONFIGURATION.md) → [Example Code](docs/EXAMPLES.md) |
| **System Administrator** | Email Configuration → Security Settings | [Configuration Guide](docs/CONFIGURATION.md) → [Troubleshooting](docs/TROUBLESHOOTING.md) |
| **Developer** | Development Environment → API Usage | [Development Guide](docs/DEVELOPMENT_GUIDE.md) → [API Documentation](docs/API.md) |
| **DevOps** | Deployment Configuration → Monitoring and Maintenance | [Client Configuration](docs/MCP_CLIENT_SETUP.md) → [FAQ](docs/FAQ.md) |
## Complete Documentation
View [Documentation Center](docs/README.md) for complete project documentation.
## Project Quality Assurance
### Code Quality Standards
- [OK] **Ruff** Code format checking and static analysis
- [OK] **MyPy** Strict type checking (–strict mode)
- [OK] **Pylance** IDE static analysis passed
- [OK] **87.22% Test Coverage**, enterprise-level standards
### Testing Strategy
- **Unit Testing**: Covers all core functional modules
- **Integration Testing**: MCP protocol communication testing
- **Boundary Testing**: Error handling and exception situations
- **Performance Testing**: Large file and concurrent processing
### Continuous Integration
- **Automated Testing**: Runs complete test suite on every commit
- **Code Quality Checking**: Automatically runs Ruff and MyPy
- **Coverage Monitoring**: Ensures test coverage does not decrease
## Limitations and Precautions
- Single attachment size limit: 25MB
- Remote file download uses system proxy
- Supported file formats: All common file types
- Network exception automatic retry 3 times
## License
MIT License
## Contribution
Feel free to submit Issues and Pull Requests!
