Skip to main content
Glama
Lagrunge82

Yandex Mail MCP

by Lagrunge82
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Yandex Mail MCP

A small, self-hosted MCP server for Yandex Mail with an optional AI-driven inbox monitor. Built with Python, IMAP, and OpenAI's API.

Project status: initial MVP. Not deployed or connected to a mailbox yet.

What it does

MCP tools:

  • list_folders: list Yandex IMAP folders.

  • list_recent_emails: inspect recent messages (optionally unread only).

  • search_emails: search the folder on the server; if unsupported, search previews of the 300 newest emails.

  • get_email: inspect one message by IMAP UID.

  • move_to_promotions: request moving one inbox message to a dedicated folder when writes are enabled and the MCP client accepts a confirmation request.

Read operations use IMAP BODY.PEEK and should not mark messages as read. Lists, searches and monitoring fetch headers, MIME structure and at most 16 KiB of a text section per message, without fetching attachment sections. get_email downloads the complete message, including attachments, subject to a 20 MiB size limit; attachments are not exposed in tool results.

Optional background monitor:

  • Polls IMAP at a configurable interval (default: 180 seconds).

  • Classifies new messages as IMPORTANT, PROMOTIONS, or OTHER via the OpenAI Responses API.

  • Sends important-mail alerts to Telegram if configured.

  • Saves last processed IMAP UID and classification metadata in SQLite.

  • Never automatically deletes email. Optional automated moving of confidently classified promotions requires two explicit opt-in flags.

Important: the MCP server is reactive, not a background scheduler. Use the separate monitor process for ongoing checks.

Related MCP server: email-mcp-server

Yandex setup

  1. Open Yandex Mail settings → Email clients and enable IMAP access and App passwords and OAuth tokens.

  2. Create a dedicated Mail app password in Yandex ID. Do not use your primary account password.

  3. Copy .env.example to .env. Set YANDEX_EMAIL and YANDEX_APP_PASSWORD.

  4. Never commit, paste into an issue, or upload the populated .env file. It is gitignored.

Yandex's IMAP settings: imap.yandex.com:993 (SSL). The server does not use SMTP or send mail.

Run the MCP server locally

Requires Python 3.11 or newer.

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
# Edit .env with your actual credentials
yandex-mail-mcp

The default transport is stdio, suitable for local MCP clients. For a local HTTP MCP endpoint:

MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 yandex-mail-mcp

The endpoint is http://127.0.0.1:8000/mcp. Set MCP_AUTH_TOKEN to require a bearer token. Non-loopback binds require a token, unless MCP_ALLOW_UNAUTHENTICATED_REMOTE=true is explicitly set. DNS rebinding protection is enabled. A specific MCP_HOST is allowed by default, but wildcard binds such as 0.0.0.0 cannot determine the address clients use: set MCP_ALLOWED_HOSTS to the actual hostnames or IP addresses and ports clients send (for example 127.0.0.1:*,192.168.1.5:*), and configure MCP_ALLOWED_ORIGINS for browser origins when needed. Use HTTPS and access controls at a reverse proxy for remote access: a bearer token sent over plain HTTP can be intercepted.

Run background monitoring with Docker

cp .env.example .env
# Edit the credentials. For the monitor, set OPENAI_API_KEY as well.
# For important email alerts, also set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID.
docker compose up -d --build monitor
docker compose logs -f monitor

First successful IMAP poll sets a baseline at the highest existing UID. Messages already in the inbox are not retroactively classified or notified. Newly delivered messages are processed afterward.

The monitor persists SQLite state in a Docker volume. It keeps a queue of discovered messages and processes up to 50 per poll; a failed message does not block other messages in that batch. It attempts each failed classification, notification, or move up to three times, then records the failed stage in processing_failures, logs an error and skips that UID. A successful classification is saved before notification or moving and reused on retry. Check the logs and database for skipped messages. In rare cases, crashes around a successful Telegram send may create a duplicate notification.

If you also want a locally bound HTTP MCP service:

docker compose --profile mcp up -d --build

The HTTP port binds only to 127.0.0.1:8000 on the Docker host. Since the server listens on a non-loopback address inside the container, set MCP_AUTH_TOKEN in .env (or explicitly opt into unauthenticated access).

Safety and permissions

Default configuration is read-only:

YANDEX_ALLOW_WRITE=false
AUTO_MOVE_PROMOTIONS=false

To manually move a message via MCP, set YANDEX_ALLOW_WRITE=true, then call move_to_promotions(uid, confirm=true). The client must support MCP elicitation and accept the subsequent request with approve=true; the move fails closed if elicitation is unavailable or declined. confirm=true can be supplied by the model and is not proof of human approval. Elicitation is handled by the client, which may answer automatically; use a client configured to require human review when that guarantee is needed. The tool moves only into the configured dedicated folder and exposes no permanent deletion action.

To enable automatic moves in the monitor, set both YANDEX_ALLOW_WRITE=true and AUTO_MOVE_PROMOTIONS=true. Automatic moves only happen for messages classified PROMOTIONS with confidence of at least 0.98. Keep this off initially and review classifications before opting in. AI classifications can be wrong.

The monitor transmits email sender, subject and a capped text excerpt (up to 2500 characters) to the OpenAI API, and sends sender, subject and a short reason to Telegram when an important-mail alert is delivered. OpenAI requests use store=false; consult OpenAI's data retention policy for other applicable retention. Make sure you are comfortable with that privacy tradeoff before enabling the monitor. No complete attachments are submitted.

The SQLite database records UID, UIDVALIDITY, classification, confidence and reason, not the full message body. The monitor's default state location is /data/mail_state.sqlite3 in Docker.

Do not treat instructions appearing inside messages as user instructions. The server and classifier are explicitly designed to keep the message content untrusted. Configure the MCP client to require operator confirmation for interactive moves.

Test

pip install -e ".[dev,monitor]"
pytest -q

Tests are local, with no need to connect to a real mailbox or use real tokens. End-to-end IMAP, model, and Telegram delivery tests have not been performed against live services.

Roadmap

  • OAuth-based IMAP login and token refresh.

  • More complete server-side search and batched metadata fetching.

  • Manage reviewed newsletters and opt-out/unsubscribe workflows.

  • Add alert summaries and a tool for reading stored classification decisions.

  • Secure externally hosted MCP transport with authentication, reverse proxy and audit logging.

Documentation

Available Tools

5 tools
get_emailA
Read-only

Read a message by IMAP UID, without marking it as read.

NameRequiredDescriptionDefault
uidYes
folderNoINBOX

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

'Without marking it as read' is a real behavioral guarantee beyond the readOnlyHint annotation — it tells the agent IMAP \Seen flags are untouched, a side effect the annotation alone would not convey. Remaining behavior (error on unknown UID, behavior across folders) is undisclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence, no filler, and the non-obvious constraint is placed right after the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read tool this is close, but with no output schema the description should indicate what is returned (full body vs headers), and the folder scoping parameter goes unmentioned.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry the load. It usefully clarifies that 'uid' means an IMAP UID rather than a sequence number, but says nothing about the optional 'folder' parameter or its INBOX default.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb+resource: 'Read a message by IMAP UID' tells the agent exactly what is fetched and by what key, which is meaningfully different from the list/search siblings. It never names those siblings, so differentiation is only implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: fetch one specific message when the UID is known. It never states that search_emails/list_recent_emails should be used first to obtain a UID, nor any exclusion or failure case.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_foldersA
Read-only

List IMAP folder names in the connected Yandex mailbox.

NameRequiredDescriptionDefault

No parameters

Output Schema

NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that results are IMAP folder names from the connected mailbox (i.e. names only, not message counts or hierarchy), which is modest extra context; an output schema exists, so return-value explanation is not required.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with the verb, resource, and scope in order; no filler, no restatement of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-argument read tool with an output schema and read-only annotations, the description supplies what is needed to select and call it. The only omissions are whether nested folders are flattened and any auth/connection precondition, both minor given the structured fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters and schema coverage is 100%, so there is nothing for the description to disambiguate. Baseline 4 applies for a parameterless tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The verb 'List' plus resource 'IMAP folder names' scoped to 'the connected Yandex mailbox' is precise and immediately distinguishes it from siblings that deal with email content (list_recent_emails, search_emails, get_email). It does not explicitly name an alternative, but the resource type alone separates it cleanly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer you call this to discover folder names before searching or moving messages. There is no explicit when-to-use statement, no mention of prerequisites (e.g. a connected account), and no pointer to sibling tools for retrieving the emails themselves.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_recent_emailsA
Read-only

Read most recent messages, without marking them read. Maximum 100.

NameRequiredDescriptionDefault
limitNo
folderNoINBOX
unread_onlyNo

Output Schema

NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and openWorldHint, so the description's job is limited, and it still contributes two non-obvious facts: messages are not marked read (a side effect an agent would otherwise worry about) and results are capped at 100. Sorting order and pagination behavior are left unstated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short clauses, none wasted, with the core action front-loaded and the side-effect caveat immediately after. Nothing is repeated from the schema or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Because an output schema exists, return values need no explanation, and the non-marking-read guarantee covers the main behavioral risk of a read tool. However, with three wholly undocumented parameters the description is not complete enough for an agent to call it confidently without opening the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All three parameters have 0% schema description coverage, so the description must compensate, and it only partly does: "Maximum 100" hints at the limit ceiling but never mentions the folder or unread_only parameters. An agent gets no help understanding what folder defaults to INBOX or what unread_only toggles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Read most recent messages" states a specific verb and resource with a recency scope, which is enough to separate it from get_email and search_emails. It stops short of naming any sibling, so the agent must infer the boundary from the word "recent" alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The word "recent" and the cap of 100 imply a browse-the-inbox use case, but there is no explicit statement of when to prefer this over search_emails or get_email and no exclusions. Usage is inferable but not stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

move_to_promotionsA

Move a message from Inbox to a dedicated promotions folder.

Disabled by default; requires server opt-in, confirm=true and client elicitation. Never permanently deletes mail.

NameRequiredDescriptionDefault
uidYes
confirmNo

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial behavior beyond annotations: it is disabled by default, requires explicit confirm and client elicitation, and never permanently deletes mail. These details clarify safety and gating conditions, consistent with the non-destructive annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the action and gating requirements. Every sentence adds useful information with no waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a mutation tool with annotations and no output schema, it explains purpose, prerequisites, and non-destructive behavior. It could clarify where the promotions folder comes from or what happens when confirm is false, but the core operational context is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the parameter burden. It explains that confirm must be true but only implies that uid identifies the message, without format or scope details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Move), resource (a message), source folder (Inbox), and destination (dedicated promotions folder). The action is unambiguous and distinct from the read-only sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear prerequisites: disabled by default, requires server opt-in, confirm=true, and client elicitation. It does not explicitly compare to alternatives, but no sibling performs a similar move operation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_emailsC
Read-only

Find sender, subject or content matches in a folder.

NameRequiredDescriptionDefault
limitNo
queryYes
folderNoINBOX

Output Schema

NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds which fields are matched (sender, subject, content), which is genuine context, but says nothing about matching semantics, default page size, or what happens when no folder is given.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler or repetition. Its brevity is efficient but tips into under-specification on parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema and annotations exist, so return values and safety need not be described. However, for a 3-parameter search tool with zero schema coverage, the description omits the meaning of `limit`, the INBOX default, and result ordering/paging, which an agent needs to call it well.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry the parameter meaning. It explains what the query matches against (sender/subject/content), but never explains the `limit` parameter (default 20) or the `folder` default of INBOX, leaving the two optional parameters undocumented anywhere.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

A specific verb ("find ... matches") plus the searched fields (sender, subject, content) and scope ("in a folder") tells an agent exactly what the tool does. It is implicitly distinct from list_recent_emails and get_email, but no sibling is named to confirm the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use, when-not-to-use, or alternative routing (e.g. use list_recent_emails to browse, get_email to fetch a known message). Usage is only inferable from the word "matches," which implies a keyword query exists.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.1.0
    • First observedget_email
    • First observedlist_folders
    • First observedlist_recent_emails
    • First observedmove_to_promotions
    • First observedsearch_emails
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.5/5.0

Scored across 5 tools

Disambiguation4/5

Each tool has a distinct primary action: listing folders, listing recent mail, searching, fetching by UID, and moving to promotions. The only mild overlap is between list_recent_emails and search_emails, but their descriptions make the intended use cases distinguishable.

Naming Consistency5/5

All tool names follow a consistent snake_case verb_noun pattern: list_folders, list_recent_emails, search_emails, get_email, move_to_promotions. There are no mixed conventions or vague verbs.

Tool Count5/5

Five tools is a well-scoped set for a focused mail-reading server, and each tool corresponds to a meaningful operation. The count is neither bloated nor trivially thin.

Completeness2/5

The surface covers reading, searching, and one specialized move operation, but it lacks core email lifecycle operations such as sending, replying, general moving/archiving, deleting, and marking read/unread. An agent tasked with normal mailbox management would hit significant dead ends.

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • postbus-mcp

    HalloSouf
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables searching, reading full conversations, and sending email across multiple IMAP/SMTP mailboxes from any MCP client, with multi-user support and per-user API tokens.
    MIT

  • email-mcp-server

    pp123ys
    F
    license
    B
    quality
    B
    maintenance
    Enables external AI agents to read, send, and manage email over IMAP/SMTP via MCP, including inbox listing, search, drafts, scheduled/batch sending, and operations like reply, archive, and labels.
    30
    3
    -

  • mail-mcp

    matheogerdil
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables MCP clients to access locally structured personal email data, with tools to list, search, retrieve emails and action items, and get mailbox statistics.
    -