Skip to main content
Glama
Yandex Mail MCP

Yandex Mail MCP

by Lagrunge82

Yandex Mail MCP

A small, self-hosted MCP server for Yandex Mail. Built with Python and IMAP. It reads mail without marking it read, and changes mail only behind an explicit opt-in and a confirmation from the user.

Project status: early development (0.x). Tagged releases and container images are published, but tool names, parameters and configuration may still change between minor versions. See CHANGELOG.md.

What it does

Read tools, always available:

  • list_folders: list the mailbox's IMAP folders, named as the server reports them (Yandex separates nested folders with |).

  • list_recent_emails: inspect the most recent messages of a folder, newest first, optionally unread only.

  • search_emails: search a folder by any combination of query (IMAP SEARCH TEXT, which matches headers and body as the server indexes them), sender, to, subject, since and before (YYYY-MM-DD; IMAP compares dates without time, in the server's time zone), unread, flagged and has_attachments. The server evaluates every criterion except has_attachments, which is checked against the MIME structure of at most the 500 newest messages matching the rest. If the server rejects a search by query alone, it falls back to the 300 newest messages and matches only the sender, subject and the first 2000 characters of the text preview, so results can differ from a server search; searches with other criteria report the server error instead. Yandex evaluates query, sender, to and subject against a search index that lags behind delivery: a message that arrived minutes ago is listed by list_recent_emails and found by since, unread or flagged, but may not match text criteria yet. For the newest mail, list the folder or search by date.

  • get_email: inspect one message by IMAP UID.

  • get_thread: collect the conversation a message belongs to, oldest first, by following Message-ID, In-Reply-To and References through the message's folder, INBOX and the folder flagged \Sent. Each result names its folder. Yandex can fail a search by Message-ID with [UNAVAILABLE] UID SEARCH Backend error; the earlier messages of the thread are then found by subject among at most 200 messages per folder, and compared by Message-ID.

Changing tools, which need YANDEX_ALLOW_WRITE=true, act on one message per call (or on one reviewed batch with move_emails) and ask the user to confirm (see Safety and permissions):

  • move_email: move one message to an existing folder.

  • move_emails: move up to 25 messages from one folder to another in one step. The confirmation lists every message with its sender and subject. One IMAP MOVE carries the batch; since a server may move part of it, the result reports moved and not_moved from the server's COPYUID response, or, on a server without UIDPLUS, which UIDs are still in the source folder and a warning to check the destination.

  • archive_email: move one message to the archive folder: YANDEX_ARCHIVE_FOLDER, or the folder the server flags \Archive.

  • mark_read: mark one message read or unread.

  • set_flag: flag or unflag one message.

  • create_draft: save a plain-text draft, optionally a reply that joins a message's conversation, in the folder flagged \Drafts. Nothing is sent: the user reviews and sends it from Yandex Mail.

  • move_to_promotions: deprecated in favor of move_email and will be removed in a later release. Moves one inbox message to the dedicated folder YANDEX_PROMOTIONS_FOLDER, creating it if missing.

get_connection_capabilities reports what the current connection may do: whether the server allows changes, which MCP scopes the connection holds, whether the Yandex authorization behind it has full IMAP access, whether the client can confirm changes itself or through a link, and what to do when changes are unavailable. It reveals no tokens or secrets.

On the shared HTTP server, logout signs the calling connection out: the server stops accepting every token of that sign-in at once, then revokes its Yandex token. Mail is not changed. The user's other connections keep their own sign-ins, unless Yandex ends them too because they share its grant. If Yandex cannot be reached, the result says so and suggests revoking the application in Yandex ID. The local server has the logout command instead.

The server exposes no deletion, expunge, move to Trash, or sending of mail.

Results

Every message result has uid, message_id, subject, from, to, date (ISO 8601 when the header parses), preview, has_attachments, attachments, list_unsubscribe (the raw header; the server never follows unsubscribe links or sends unsubscribe mail), in_reply_to and references. get_thread results add folder.

  • UIDs are unique only within a folder. Pass the same folder to get_email, get_thread and the changing tools that you listed or searched with. A message moved to another folder gets a new UID there.

  • Paging: list_recent_emails and search_emails return at most 100 messages per call. For the next page, pass the smallest uid of a page as before_uid.

  • Previews are the message's first text/plain part, or its first text/html part converted to text, collapsed to single spaces. Lists and searches fetch headers, the MIME structure and at most 16 KiB of that part per message, without fetching attachment sections; the preview is cut at 4000 characters in list_recent_emails and 2000 in search_emails and get_thread. get_email downloads the complete message, including attachments, subject to a 20 MiB size limit, and returns up to 10000 characters.

  • Attachments: contents are never returned; attachments lists each part's file name, content type, size and IMAP section. Any part that is not text or multipart, has a file name, or has an attachment disposition counts, so inline images in HTML signatures and attached messages count as attachments. The size is the encoded size stored in the message, about a third larger than the file for base64 content.

  • Read operations never mark mail as read: they use IMAP BODY.PEEK and select folders read-only.

Related MCP server: email-mcp-server

Quick start for one user (stdio)

The server signs in to IMAP with a Yandex OAuth token (AUTHENTICATE XOAUTH2); no password is needed. Requires Python 3.11 or newer and uv.

  1. In Yandex Mail settings → Email clients, enable IMAP access and App passwords and OAuth tokens. For a Yandex 360 account, the administrator must also allow OAuth access to mail.

  2. Register an application at oauth.yandex.ru of the type for user authorization («Для авторизации пользователей»; Yandex instructions). The type for API access or debugging cannot use a loopback redirect. Choose the Web services platform with the redirect URI http://127.0.0.1:8765/callback (the port is YANDEX_OAUTH_LOOPBACK_PORT), and the permissions login:email, login:info, mail:imap_ro (reading mail) and mail:imap_full (shown by Yandex as reading and deleting mail; the server never deletes). Signing in works with PKCE alone, without the client secret; still set YANDEX_OAUTH_CLIENT_SECRET, since token refresh has only been checked with it.

  3. Install, configure and sign in:

    uv sync --locked
    cp .env.example .env
    # Set YANDEX_OAUTH_CLIENT_ID (and YANDEX_OAUTH_CLIENT_SECRET if Yandex issued one).
    uv run yandex-mail-mcp login

    A browser opens the Yandex sign-in page. After you allow access, the tokens are saved in the system keyring, or in ~/.config/yandex-mail-mcp/tokens.json (mode 0600, with a warning) where no keyring exists. The server refreshes the access token itself, which needs the same YANDEX_OAUTH_CLIENT_ID (and secret, if one was used at login) in its environment.

  4. Add the server to your MCP client as a stdio command, for example in Claude Desktop's claude_desktop_config.json:

    {"mcpServers": {"yandex-mail": {"command": "uv", "args": ["--directory", "/path/to/yandex-mail-mcp", "run", "yandex-mail-mcp"]}}}

    or with Claude Code: claude mcp add yandex-mail -- uv --directory /path/to/yandex-mail-mcp run yandex-mail-mcp. Variables can also be passed in the client's env block instead of a .env file. The server logs to standard error, so logging never corrupts the stdio transport.

uv run yandex-mail-mcp logout revokes the token at Yandex and deletes it. Without YANDEX_ALLOW_WRITE=true, login asks only for read-only IMAP access; with it, for full access. A read-only token makes the changing tools fail with a hint to sign in again.

Credentials come from the first of these that is set: YANDEX_OAUTH_TOKEN with YANDEX_EMAIL (a ready access token, for CI and containers; it cannot be refreshed), then the tokens saved by login. The app password of earlier releases is no longer accepted: a set YANDEX_APP_PASSWORD stops the server with a message pointing at login.

For a single-user HTTP endpoint on this machine, set MCP_TRANSPORT=streamable-http: the endpoint is http://127.0.0.1:8000/mcp, reachable without a token from the loopback interface only. A non-loopback MCP_HOST requires MCP_PUBLIC_URL (below); the static MCP_AUTH_TOKEN of earlier releases is no longer accepted.

Shared server for several users (HTTP)

With MCP_PUBLIC_URL set, the HTTP server is an OAuth authorization server for MCP clients: each person adds the server's URL to their client, signs in with Yandex in the browser and works with their own mailbox. The server stores no user tokens or passwords (see Security).

  1. Register a Yandex OAuth application as above, with the redirect URI <MCP_PUBLIC_URL>/oauth/yandex/callback, for example https://mail.example.com/oauth/yandex/callback. Note its client ID and client secret.

  2. Generate an encryption key:

    python -c "import secrets, base64; print('k1:' + base64.urlsafe_b64encode(secrets.token_bytes(32)).decode())"
  3. In .env, set:

    Variable

    Value

    MCP_PUBLIC_URL

    The HTTPS URL clients use, such as https://mail.example.com. It is the issuer, the resource (<url>/mcp) and the base of the Yandex redirect URI.

    MCP_TOKEN_ENCRYPTION_KEYS

    The generated key.

    MCP_ALLOWED_USERS

    Comma-separated Yandex logins or addresses allowed to sign in. Empty refuses everyone.

    YANDEX_OAUTH_CLIENT_ID, YANDEX_OAUTH_CLIENT_SECRET

    The application from step 1.

    YANDEX_ALLOW_WRITE

    true to offer the changing tools; each user still has to grant full IMAP access.

  4. Start it with Docker Compose (docker compose up -d --build), which binds 127.0.0.1:8000 on the host and keeps the registered clients in the auth volume (MCP_AUTH_DB). Compose refuses to start without the variables above. The volume also keeps the list of revoked sign-ins. Losing it makes MCP clients register again and forgets that list, so tokens revoked in the last 30 days would work again until they expire. After such a loss, replace MCP_TOKEN_ENCRYPTION_KEYS with a new key, which ends every token issued so far.

  5. Put an HTTPS reverse proxy in front of it. Without HTTPS, tokens travel in clear text. With Caddy, which obtains the certificate itself, a Caddyfile of two lines is enough:

    mail.example.com
    reverse_proxy 127.0.0.1:8000
  6. Add the connector: in Claude Desktop, Settings → Connectors → Add custom connector with the URL https://mail.example.com/mcp; in Claude Code, claude mcp add --transport http yandex-mail https://mail.example.com/mcp, then /mcp to sign in. The client registers itself and opens the sign-in flow. When the server allows writes, a page on this server first asks whether the app may read only or read and change mail; Yandex then shows its own permission page. See Write access and confirmations.

Requests to /authorize, /token, /register, /revoke and the Yandex sign-in routes are limited to MCP_AUTH_RATE_LIMIT (30) per client IP and minute. Compose sets MCP_FORWARDED_ALLOW_IPS=* so the limit sees the client addresses the proxy forwards; this is safe only because the port is bound to localhost. Each tool call writes a JSON line to the yandex_mail_mcp.audit log with the time, Yandex login, client ID, tool, folder, UID, result and duration, without subjects, addresses, message text or tokens.

GET /healthz answers 200 ok while the HTTP server is serving, without logging in to IMAP or requiring a token; Compose uses it as the health check. DNS rebinding protection is enabled: the host of MCP_PUBLIC_URL and a specific MCP_HOST are allowed automatically, and MCP_ALLOWED_HOSTS and MCP_ALLOWED_ORIGINS override the defaults. A wildcard bind such as 0.0.0.0 without MCP_PUBLIC_URL needs MCP_ALLOWED_HOSTS set to the host names or addresses and ports clients send.

Write access and confirmations

Changing mail takes three separate permissions, and all three are checked on every call:

  1. The operator enables changes with YANDEX_ALLOW_WRITE=true. Without it the server never asks Yandex for more than read access and never offers the mail.write scope.

  2. The user grants them when connecting. On the shared HTTP server a consent page asks whether the app may read only or read and change mail; only the second choice makes the server request full IMAP access (mail:imap_full) from Yandex, and Yandex shows its own permission page after it. The MCP token gets the mail.write scope only when the user chose it and Yandex granted full access. A client that asks for mail.read alone goes straight to read-only access and sees no page. On the local server, yandex-mail-mcp login asks for full access when YANDEX_ALLOW_WRITE=true is set.

  3. The user confirms each change. Every changing tool shows what it is about to do before doing it, with each message's sender and subject marked as untrusted text: one message per call, or, with move_emails, one list of up to 25 messages approved together. Clients with MCP elicitation (Claude Desktop, Claude Code) ask inside the conversation. A client that declares elicitation but connects over a transport that cannot carry the question (the stateless HTTP server, or the single-exchange protocol of 2026-07-28, where the SDK raises NoBackChannelError) is treated as one without it. On the shared HTTP server, such a client, or one without elicitation, gets a link instead: the tool returns confirmation_required with a confirm_url on this server, where the user, signed in as the same Yandex account, sees the change and approves or rejects it. Nothing happens until they approve; the link is single-use and expires in 10 minutes. Changing the Seen and Flagged flags and saving a draft are reversible, so the operator can skip their confirmation with MCP_CONFIRM_REVERSIBLE=false; moves and archiving are always confirmed.

The confirmation page relies on a cookie set in the browser that completed the Yandex sign-in, so it is normally available right away. In another browser, or after 30 days, the page first sends the user through a Yandex sign-in that asks only for their login, then shows the change. The assistant cannot approve on the user's behalf: the page needs that browser session, and approving is a form submission from it. The server accepts the decision only from its own origin, by Origin, or Referer when a browser drops Origin. The form must also carry a token issued for this change to this browser. So knowing the link is not enough, even for a page on a sibling subdomain that receives the session cookie. The server's pages cannot be shown inside another site's frame.

ChatGPT

ChatGPT connects to the shared HTTP server as any other MCP client, with the same consent page. Its OAuth client asks for the scopes this server publishes in its protected-resource metadata, which include mail.write when writes are enabled, so the consent page appears and the user chooses. Whether a given ChatGPT connection can confirm changes through elicitation is best checked with get_connection_capabilities: confirmation is elicitation when it can, and browser_link when changes will be confirmed through the link described above (transport_delivers_elicitation says whether the connection could carry a question at all). Both work; the link is the fallback for clients that cannot ask.

Upgrading a read-only connection

A connection authorized before writes were enabled, or with read only chosen on the consent page, keeps read-only tokens for as long as it refreshes them: refreshing never widens a token. To get write access, authorize again:

  1. The operator sets YANDEX_ALLOW_WRITE=true and restarts the server.

  2. In the client, disconnect and reconnect the server (ChatGPT: remove the connector and add it again, or use its reauthorize option when offered; Claude Desktop: remove and re-add the custom connector; Claude Code: claude mcp remove yandex-mail, add it again and run /mcp).

  3. On the consent page choose Read and change mail, then allow full access on Yandex's page.

Clients registered while writes were off can do this without re-registering: what a client may ask for follows the server's current configuration. Tokens issued earlier stay read-only until they expire or are refreshed into nothing wider than they were.

Troubleshooting

  • "Your access is read-only. Sign in again with write access: reconnect this server in your MCP client and allow full mail access" means this connection's token lacks mail.write: either the connection was authorized before YANDEX_ALLOW_WRITE=true, or read only was chosen, or Yandex granted only mail:imap_ro. Reconnecting alone does not help if the client reuses its refresh token; follow Upgrading a read-only connection. get_connection_capabilities shows mcp_scopes and yandex_full_mail_access for the connection.

  • "Write operations are disabled. Set YANDEX_ALLOW_WRITE=true": the server itself refuses changes; this is the operator's setting.

  • "… needs the user's confirmation, but this MCP client does not support elicitation" (or "… declares elicitation, but its transport cannot deliver the confirmation request") appears only on the local server: there is no browser identity to confirm with. Use a client with elicitation over a transport that carries it, or the shared HTTP server.

  • "IMAP login was dropped twice (…); the mail server may be limiting sessions, retry later": a new IMAP connection lost its session while logging in, and again a second later. The parentheses hold the server's reason. Yandex drops sessions idle for about four minutes, so this follows a pause; check other IMAP clients on the mailbox and try YANDEX_IMAP_POOL_SIZE=1.

  • "IMAP connection was interrupted twice; the mail server may be closing sessions, retry later": a read-only call lost its IMAP session, and the retry on a new connection lost it too. The server's warnings name the reason Yandex gave. Check whether other IMAP clients use the same mailbox, since Yandex limits concurrent sessions per account, and try YANDEX_IMAP_POOL_SIZE=1. uv run python scripts/imap_stress.py runs 20 read-only calls one after another and 20 at once against the configured mailbox and reports failures, response times and dropped sessions, then times UID SEARCH ALL over the folder against the windowed FETCH that list_recent_emails uses; it changes nothing and prints no message content. "IMAP connection was interrupted; please retry" comes from a change, which is not retried: check the mailbox before repeating it.

  • "Folder 'github/ci/cd' not found": nested folders are written with the server's delimiter, | on Yandex (github|ci/cd); the error names the folder it thinks you meant. list_folders shows the exact names.

Configuration

Settings come from environment variables. The server and the login and logout commands also read a .env file, found by searching upward from the installed package (the project checkout when installed with uv sync or pip install -e .), and never override a variable that is already set. Booleans accept 1, true, yes and on; a blank value means the default.

Variable

Default

Meaning

YANDEX_OAUTH_CLIENT_ID

empty

The Yandex OAuth application. Needed by login, by the stdio server to refresh the saved tokens, and by the shared HTTP server.

YANDEX_OAUTH_CLIENT_SECRET

empty

Its secret. login uses PKCE and signs in without it, but token refresh has only been checked with the secret set.

YANDEX_OAUTH_LOOPBACK_PORT

8765

Port of the http://127.0.0.1:<port>/callback redirect URI that login listens on.

YANDEX_OAUTH_TOKEN

empty

A ready Yandex access token, used with YANDEX_EMAIL instead of login. It cannot be refreshed.

YANDEX_EMAIL

empty

The mailbox address, required with YANDEX_OAUTH_TOKEN.

YANDEX_IMAP_HOST

imap.yandex.com

IMAP server.

YANDEX_IMAP_PORT

993

IMAP port, 1 to 65535; the connection always uses TLS.

YANDEX_IMAP_POOL_SIZE

2

Logged-in IMAP connections kept and reused across tool calls, at least 1: per user on the local server, per sign-in on the shared server.

YANDEX_IMAP_IDLE_TIMEOUT

300

Seconds an idle connection is kept before it is replaced.

YANDEX_ALLOW_WRITE

false

Enables the changing tools. login then asks for full IMAP access; HTTP users must grant it too.

MCP_CONFIRM_REVERSIBLE

true

Set to false to change the Seen and Flagged flags and save drafts without a confirmation request. Moves are always confirmed.

YANDEX_ARCHIVE_FOLDER

empty

Destination of archive_email; empty means the folder the server flags \Archive. Never created.

YANDEX_PROMOTIONS_FOLDER

AI-Promotions

Destination of the deprecated move_to_promotions. Must be a top-level, non-system folder.

MCP_TRANSPORT

stdio

stdio or streamable-http.

MCP_HOST

127.0.0.1

HTTP bind address.

MCP_PORT

8000

HTTP port, 1 to 65535.

MCP_PUBLIC_URL

empty

The HTTPS URL of the shared HTTP server; setting it turns on OAuth sign-in for several users.

MCP_TOKEN_ENCRYPTION_KEYS

empty

kid:base64key pairs, newest first, that seal the tokens the shared server issues. Required with MCP_PUBLIC_URL.

MCP_ALLOWED_USERS

empty

Yandex logins or addresses allowed on the shared server, comma-separated. Empty refuses everyone.

MCP_AUTH_DB

mcp-auth.db

SQLite file of the MCP clients registered with the shared server, the revoked sign-ins and the refresh generation of each sign-in.

MCP_AUTH_RATE_LIMIT

30

Requests per client IP and minute to the sign-in and token endpoints.

MCP_FORWARDED_ALLOW_IPS

empty

Proxies whose X-Forwarded-For the HTTP server trusts for client addresses.

MCP_ALLOWED_HOSTS

localhost:*,127.0.0.1:*,[::1]:*, plus MCP_HOST:* for a specific address and the host of MCP_PUBLIC_URL

Host header values accepted by the DNS rebinding protection.

MCP_ALLOWED_ORIGINS

http://localhost:*,http://127.0.0.1:*,http://[::1]:*, plus the origin of MCP_PUBLIC_URL

Origin header values accepted from browsers.

The server keeps up to YANDEX_IMAP_POOL_SIZE logged-in IMAP connections per user and reuses them across tool calls, so a series of calls logs in once. Yandex limits concurrent IMAP sessions per account, so keep the pool small. A call that finds every connection busy waits up to a minute, then fails with an error. A connection idle longer than YANDEX_IMAP_IDLE_TIMEOUT seconds or failing NOOP is replaced. Connections are returned with no folder selected, closed after a failed call, and logged out when the server stops. When the server drops a session in the middle of a call (BYE, a closed or reset socket), the pool also closes its idle connections, which have probably been dropped too, without waiting for LOGOUT. The read-only tools list_folders, list_recent_emails, search_emails, get_email and get_thread then run the whole call once more on a new connection; a second drop in a row reaches the client as an error. A new connection whose login is dropped (BYE, end of stream, a reset) logs in once more after a second, for every tool, changes included, since nothing but the login was sent; a login refused for its credentials or a timeout is not retried. Changes are never repeated, since the session may drop after the server made the change, and neither is a call that timed out. Each dropped session is logged as a warning with the operation, the error and the server's reason, the connection's age and number of calls, never message content. On the shared server each sign-in has its own pool, so connections logged in with one sign-in's token never serve another; the server checks every 30 seconds for pools unused for YANDEX_IMAP_IDLE_TIMEOUT seconds, but at least a minute, and closes them. A revoked sign-in's pool is closed at once. Yandex's IMAP server is imap.yandex.com:993 (SSL); the server does not use SMTP or send mail.

Security

  • No user tokens are stored. The server issues its own tokens, and each one carries the user's Yandex token inside, encrypted with AES-256-GCM under MCP_TOKEN_ENCRYPTION_KEYS. A Bearer token holds the Yandex access token, login, address and granted scope, the client ID, the random id of the sign-in and the expiry; a refresh token holds the Yandex refresh token instead. Access tokens last an hour (less if the Yandex token expires sooner), refresh tokens 30 days, authorization codes 60 seconds. The only file holds the table of registered MCP clients, whose secrets are encrypted too, the random ids of revoked sign-ins, and the refresh generation each sign-in is at, each kept for 30 days.

  • Refresh tokens rotate. Each refresh returns a new refresh token and spends the one used. A refresh token used a second time, by the client or by someone with a copy, revokes its whole sign-in, so both holders have to sign in again. Two refreshes with one token at once count as a second use. This does not depend on Yandex, whose own refresh token may stay the same. A refresh that fails before a new token is issued, at Yandex or because the request was cancelled, spends nothing, and the client may retry with the same token.

  • What the server holds is the encryption key and the Yandex application's client_secret. Neither is a user credential, but the key together with an intercepted token gives access to that user's mail: keep both in secret storage and serve only over HTTPS.

  • Revoking access: the logout tool, or a client's call to /revoke, revokes that sign-in. The server records it and refuses every token of the sign-in from then on, refreshed ones included, without relying on Yandex; it drops the sign-in's changes waiting for confirmation and closes its IMAP connections. It then revokes the Yandex token too. Signing in again starts a new sign-in and never revives the revoked tokens. A user can also revoke the application in their Yandex ID settings. MCP_ALLOWED_USERS decides who can sign in at all and is checked on every token, so removing a user ends their access at once; a refused user's Yandex token is revoked immediately.

  • Rotating the key: put the new key first (MCP_TOKEN_ENCRYPTION_KEYS=k2:...,k1:...); new tokens use it and old ones still open. After 30 days, when the last refresh token sealed with the old key has expired, remove it. Removing a key immediately ends every token sealed with it, and clients registered with a secret have to register again.

  • Write access requires YANDEX_ALLOW_WRITE=true on the server, the user's choice of read and change mail on the consent page, and full IMAP access granted by the user at Yandex; the server asks Yandex for full access only after that choice, and refreshing a token never widens it. Each change is then confirmed by the user, in the client or on this server's confirmation page, which only the browser that signed in can use. The server still never deletes, expunges or sends mail.

  • The local server keeps the tokens from login in the system keyring, or in a 0600 file where no keyring exists. Credentials are never logged or returned in errors, and the IMAP connection always uses TLS with certificate verification.

See SECURITY.md for reporting vulnerabilities.

Removed: app password and static token

Since 0.7.0 the server signs in to IMAP only with Yandex OAuth. YANDEX_APP_PASSWORD and the shared bearer token MCP_AUTH_TOKEN (deprecated in 0.5.0) are gone; a server started with either stops with a message naming the replacement: yandex-mail-mcp login or YANDEX_OAUTH_TOKEN for the local server, MCP_PUBLIC_URL for a server reachable from other machines. MCP_ALLOW_UNAUTHENTICATED_REMOTE was removed in 0.5.0.

Docker image

CI publishes ghcr.io/lagrunge82/yandex-mail-mcp for Linux amd64 and arm64 after the checks pass on main or a v* tag. When a push to main increases project.version in pyproject.toml, CI creates the matching Git tag (v<version>) and publishes the image with that tag. A conflicting existing Git tag fails the workflow instead of being moved. The GitHub Actions token does not trigger another workflow for the new tag, so the same run publishes the versioned image. Versions must be valid Docker tags (PEP 440 local versions with + are unsupported). A push without a previous commit to compare with (the branch's first push, or some force pushes) creates no version tag. The main image also has the latest and commit-SHA tags; manually pushed v* tags produce matching image tags. Each publication also gets a unique build-<run_id>-<run_attempt> tag. Registry tags can still be overwritten; for a strictly immutable deployment, use the image@sha256:... digest reference recorded in the workflow run summary. Package visibility is managed in GitHub Packages; access to a private image requires registry login. For example, after the first publication:

docker pull ghcr.io/lagrunge82/yandex-mail-mcp:latest

The image is based on Python 3.13, runs as an unprivileged user, owns /data for MCP_AUTH_DB and starts yandex-mail-mcp with the stdio transport by default. It contains no .env file and no browser for login, so pass a token instead, for example docker run -i --rm -e YANDEX_EMAIL -e YANDEX_OAUTH_TOKEN ghcr.io/lagrunge82/yandex-mail-mcp:latest, or use the shared HTTP server, which Compose builds from this image.

Safety and permissions

Default configuration is read-only:

YANDEX_ALLOW_WRITE=false

The folder parameter on read tools can access any folder available to the account, including Sent and Drafts. Read-only mode restricts mutations; it does not restrict which folders can be read.

To change mail via MCP, set YANDEX_ALLOW_WRITE=true and authorize the connection with write access (see Write access and confirmations). Each changing tool acts on one message and asks for confirmation through MCP elicitation: the user must accept with approve=true, otherwise nothing changes. On the shared HTTP server, a client without elicitation, or one whose transport cannot deliver the question, gets a single-use link to a confirmation page on this server instead; on the local server such a client gets an error that says so. The request names the folders involved and quotes the message's sender and subject as untrusted single lines. Moves and archiving are always confirmed. Changing the Seen and Flagged flags and saving a draft are reversible, so the operator can skip their confirmation with MCP_CONFIRM_REVERSIBLE=false. Elicitation is handled by the client, which may answer automatically; use a client configured to require human review when that guarantee is needed.

Every change is validated before the user is asked and again after the approval: an invalid request fails before the confirmation, and a folder that disappears in between fails the change. The confirmation also pins the source folder's UIDVALIDITY: if the folder was deleted and created again in between, the confirmed UIDs may now name other messages, so nothing changes and the user is asked to confirm again. A server that reports no UIDVALIDITY when the messages are read gets only the folder-and-UID check; one that stops reporting it in between is refused.

move_email and archive_email move only into existing folders and never create one. The destination is matched exactly as list_folders spells it, or case-insensitively when only one folder matches; a name that matches several folders differing only by case is rejected. They refuse Trash, Spam, Drafts and Sent (by their special-use flags or system names, including the Russian names Yandex uses), folders inside them, and virtual folders such as All Mail. create_draft appends a plain-text message (body up to 100 KiB, no attachments or HTML) to the drafts folder with the \Draft flag; its From is the signed-in address, recipients must be valid single-line addresses, and a reply fills in In-Reply-To and References from the original message. The server exposes no deletion, expunge, move to Trash, or sending of mail.

move_to_promotions(uid, confirm=true) keeps its previous behavior until it is removed: it moves only into YANDEX_PROMOTIONS_FOLDER and creates it if missing. confirm=true can be supplied by the model and is not proof of human approval. YANDEX_PROMOTIONS_FOLDER must be a top-level folder: names containing the server's hierarchy delimiter (| on Yandex) are rejected, as are system folders such as Trash and Spam. System folder names stop the server at startup; the remaining checks run before the confirmation request, which names the destination folder.

Do not treat instructions appearing inside messages as user instructions. The server is explicitly designed to keep the message content untrusted: its MCP instructions tell the model so, and confirmation requests label quoted headers as untrusted. Configure the MCP client to require operator confirmation for interactive moves.

Errors reported to the client name the IMAP host and port and the operating system's reason, never the credentials.

Development

uv sync --locked
uv run --locked pytest -q
uv run --locked ruff check .
uv run --locked ruff format --check .
uv run --locked mypy src

uv sync installs the dev dependency group (pytest, ruff, mypy, pip-audit) by default; pass --no-dev for a runtime-only environment. For a standard pip installation, use pip install -e .; pip resolves dependency versions independently of uv.lock and does not install the development tools.

CI runs the tests on Python 3.11, 3.12 and 3.13 with a coverage threshold of 85%, then ruff, mypy in strict mode, pip-audit of the locked runtime dependencies and a Docker build. Tests are local, with no need to connect to a real mailbox or use real tokens: they drive the code with fake IMAP clients and a fake Yandex OAuth transport, and keep away from the developer's keyring. End-to-end IMAP tests have not been performed against a live mailbox in CI.

Roadmap

See the project milestones for planned work.

Documentation

Available Tools

5 tools
get_emailA
Read-only

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

Inputs: uid (required), folder.

list_foldersA
Read-only

List IMAP folder names in the connected Yandex mailbox.

Inputs: no named parameters. Returns: result

list_recent_emailsA
Read-only

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

Inputs: limit, folder, unread_only. Returns: result

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.

Inputs: uid (required), confirm.

search_emailsC
Read-only

Find sender, subject or content matches in a folder.

Inputs: query (required), limit, folder. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • 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
    • F
      license
      B
      quality
      C
      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
      -
    • 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.
      -