liu10250510/mcp-email-search-server

Email Search MCP Server

A Model Context Protocol (MCP) server that enables AI agents to search and retrieve emails Yahoo accounts using keywords and time filters.

Features

• 🔍 Email Search: Yahoo Mail support with comprehensive search capabilities
• 📁 Folder Search: Search specific folders (INBOX, Sent, Drafts) or all folders
• 📅 Date range filtering: Search emails within specific time periods
• 🔑 Keyword search: Search in subject, body, and sender fields
• 📎 Attachment filtering: Find emails with or without attachments
• 🔐 Secure authentication: App Passwords for Yahoo
• 🛡️ Privacy-focused: All processing happens locally

Tools Available

search_emails

Search emails from Yahoo accounts using keywords and filters.

Parameters:

• keywords (string): Keywords to search for in email content, subject, or sender
• provider (string): Email provider to search - "yahoo"
• date_from (string, optional): Start date in YYYY-MM-DD format
• date_to (string, optional): End date in YYYY-MM-DD format
• max_results (int): Maximum results to return, 1-50 (default: 10)
• include_attachments (bool): Whether to include emails with attachments (default: false)
• folder (string): Email folder to search - "INBOX", "Sent", "Drafts", or "ALL" for all folders (default: "INBOX")

get_email_details

Get detailed content of a specific email by ID.

Parameters:

• email_id (string): The unique ID of the email to retrieve
• provider (string): Email provider - "yahoo"
• folder (string, optional): Email folder to search in (default: "INBOX")

list_email_folders

List all available email folders in your Yahoo account.

Returns: List of folder names that can be used in search operations.

check_email_config

Check the configuration status of email accounts and required environment variables.

Setup Instructions

1. Installation

git clone <repository-url>
cd mcp_email_search
pip install -e .

2. Yahoo Setup (App Password)

1. Go to Yahoo Account Security
2. Turn on 2-step verification if not already enabled
3. Generate an app password:
   • Click "Generate app password"
   • Select "Other app" and name it (e.g., "MCP Email Search")
   • Copy the generated password

3. Environment Configuration

Create a .env file in the project root:

cp .env.example .env

Edit .env with your credentials:

# Yahoo credentials
YAHOO_EMAIL=your_yahoo_email@yahoo.com
YAHOO_APP_PASSWORD=your_yahoo_app_password_here

5. Claude Desktop Configuration

Add to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "email-search": {
      "command": "python",
      "args": ["-m", "mcp_email_search.server"],
      "cwd": "/absolute/path/to/mcp_email_search"
    }
  }
}

Alternatively, if you installed the package:

{
  "mcpServers": {
    "email-search": {
      "command": "mcp-email-search"
    }
  }
}

Usage Examples

Once configured with Claude Desktop, you can use natural language commands:

Basic Search

• "Search for emails about 'meeting' from last week"
• "Find emails from john@company.com in December 2024"
• "Show me emails with attachments containing 'invoice'"

Folder-Specific Search

• "Search my Sent folder for emails about 'project alpha'"
• "Find emails in my Archive folder from this month"
• "Search my Drafts folder for unsent emails"
• "Look for emails across all my folders containing 'important'"

Folder Management

• "List my email folders"
• "What folders are available in my Yahoo account?"

Email Details

• "Get details of that email from Yahoo with ID xyz123"
• "Show me the full content of the email in my Sent folder with ID abc456"

Folder Search Features

Available Folder Options

• INBOX (default): Your main inbox folder
• Sent: Emails you've sent
• Drafts: Draft emails
• Archive: Archived emails
• Trash: Deleted emails
• Custom folders: Any custom folders you've created
• ALL: Search across all available folders

Folder Search Examples

# Search specific folder
search_emails(keywords="meeting", folder="Sent")

# Search all folders
search_emails(keywords="important", folder="ALL", max_results=20)

# List available folders
list_email_folders()

Performance Notes

• Searching specific folders is faster than searching ALL folders
• When searching ALL folders, results are limited per folder to maintain performance
• Most recent emails are prioritized in search results

Security & Privacy

• Local Processing: All email processing happens locally on your machine
• Secure Authentication: Uses industry-standard app passwords
• Read-Only Access: Only requests read permissions to your email accounts
• No Data Storage: Emails are not stored or cached by the server
• Minimal Permissions: Only accesses what's necessary for search functionality

Troubleshooting

Connection Issues

1. Run the configuration check:

   python -m mcp_email_search.server
   # Then in Claude: "Check email configuration"
   

2. Verify credentials are correctly set in .env

3. For Yahoo: Verify app password is correct and 2-factor authentication is enabled

Common Errors

• "Yahoo credentials not configured": Set YAHOO_EMAIL and YAHOO_APP_PASSWORD
• "Failed to connect to Yahoo": Check internet connection and credential validity

Development

# Install in development mode
pip install -e .[dev]

# Run the server directly
python -m mcp_email_search.server

# Test with MCP Inspector
npx @modelcontextprotocol/inspector python -m mcp_email_search.server

# Format code
black mcp_email_search/
isort mcp_email_search/

# Type checking
mypy mcp_email_search/

License

MIT License - see LICENSE file for details.