Yandex Mail MCP Server

MCP (Model Context Protocol) server for Yandex Mail. Enables Claude Desktop and other MCP clients to read, search, and send emails via Yandex Mail.

Features

• List folders — with decoded Russian folder names
• Search emails — by sender, subject, date, or custom IMAP queries (supports Cyrillic)
• Read emails — full content with text/HTML body
• Download attachments — save to disk
• Send emails — plain text or HTML
• Move/Delete emails — organize your mailbox

Installation

# Clone the repository
git clone https://github.com/yourusername/yandex-mail-mcp.git
cd yandex-mail-mcp

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure credentials
cp .env.example .env
# Edit .env with your Yandex email and app password

Yandex Setup

1. Go to Yandex ID
2. Enable Two-Factor Authentication (required for app passwords)
3. Go to Security → App Passwords
4. Create new app password for "Mail"
5. Copy the generated password to .env

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "yandex-mail": {
      "command": "/path/to/yandex-mail-mcp/.venv/bin/python",
      "args": ["/path/to/yandex-mail-mcp/server.py"]
    }
  }
}

Restart Claude Desktop after configuration.

Available Tools

Tool	Description
list_folders()	List all mailbox folders
search_emails(folder, query, limit)	Search emails with IMAP queries
read_email(folder, email_id)	Read full email content
download_attachment(folder, email_id, filename, save_dir)	Download attachment to disk
send_email(to, subject, body, cc, bcc, html)	Send an email
move_email(folder, email_id, destination)	Move email to another folder
delete_email(folder, email_id)	Delete email (move to Trash)

Search Query Examples

ALL                          # All emails
UNSEEN                       # Unread emails
FROM sender@example.com      # From specific sender
SUBJECT hello                # Subject contains "hello"
SINCE 01-Dec-2024            # Emails since date
UNSEEN FROM boss@company.com # Combined query

Running Tests

source .venv/bin/activate
pytest test_server.py -v

License

MIT