yandex-mail-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP (Model Context Protocol) server for Yandex Mail. Provides 28 email tools via IMAP/SMTP that can be used by any MCP-compatible client.

Commands

# Setup (editable install for development)
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Alternatively, run as a one-off via uvx without cloning:
uvx --from git+https://github.com/imdeniil/yandex-mail-mcp yandex-mail-mcp

# Safe tests only — unit tests + read-only integration (default)
pytest

# Verbose
pytest -v

# Unit tests only (no network at all)
pytest test_helpers.py

# Read-only integration only (requires .env credentials)
pytest test_integration.py

# DESTRUCTIVE + SEND tests — actually modifies the mailbox and sends mail.
# Opt in explicitly with --run-destructive. Tests use unique markers and
# clean up after themselves, but there's always some residual state risk.
pytest --run-destructive              # everything, including writes/sends
pytest -m destructive --run-destructive  # only destructive (folders, flags, moves)
pytest -m send --run-destructive         # only actual SMTP sends

# Single test class / case
pytest test_helpers.py::TestBodystructureParser -v
pytest test_integration.py::TestGetFolderStatus::test_has_counts -v

# Test server directly
python -c "from yandex_mail_mcp import list_folders; print(list_folders())"

Architecture

Single-file MCP server (yandex_mail_mcp.py) using FastMCP framework. 28 @mcp.tool() functions + ~18 private helpers. The module is installed via the distribution name yandex-mail-mcp on PyPI.

Tool categories:

• Read: list_folders, search_emails, read_email, download_attachment, get_folder_status, get_unread_summary, inspect_email, fetch_part
• Write: move_email, delete_email, set_flags + mark_read/mark_unread/mark_flagged/mark_answered, create_folder/rename_folder/delete_folder, empty_trash
• Bulk: bulk_set_flags, bulk_mark_read/mark_unread/mark_flagged, bulk_move, bulk_delete
• Send: send_email, reply_email, forward_email