Yandex Mail MCP
Summary: This server can browse and search Yandex Mail without marking messages read, and—only if writes are enabled and confirmed—move an inbox message to a promotions folder.
List IMAP folder names.
List recent emails in a folder (default INBOX, max 100, optionally unread only) without marking them read.
Search a folder by a text query for sender, subject or content matches.
Read a single message by IMAP UID without marking it read.
If enabled, move a message from INBOX to a dedicated promotions folder; disabled by default and requires confirmation. It never permanently deletes or sends mail.
Used by the optional inbox monitor to classify new email messages as IMPORTANT, PROMOTIONS, or OTHER via the OpenAI Responses API.
Used by the optional inbox monitor to send important-mail alerts when configured.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Yandex Mail MCP list my unread emails from the last 3 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 ofquery(IMAPSEARCH TEXT, which matches headers and body as the server indexes them),sender,to,subject,sinceandbefore(YYYY-MM-DD; IMAP compares dates without time, in the server's time zone),unread,flaggedandhas_attachments. The server evaluates every criterion excepthas_attachments, which is checked against the MIME structure of at most the 500 newest messages matching the rest. If the server rejects a search byqueryalone, 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 evaluatesquery,sender,toandsubjectagainst a search index that lags behind delivery: a message that arrived minutes ago is listed bylist_recent_emailsand found bysince,unreadorflagged, 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 followingMessage-ID,In-Reply-ToandReferencesthrough the message's folder, INBOX and the folder flagged\Sent. Each result names its folder. Yandex can fail a search byMessage-IDwith[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 byMessage-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 IMAPMOVEcarries the batch; since a server may move part of it, the result reportsmovedandnot_movedfrom the server'sCOPYUIDresponse, 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 ofmove_emailand will be removed in a later release. Moves one inbox message to the dedicated folderYANDEX_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
foldertoget_email,get_threadand the changing tools that you listed or searched with. A message moved to another folder gets a new UID there.Paging:
list_recent_emailsandsearch_emailsreturn at most 100 messages per call. For the next page, pass the smallestuidof a page asbefore_uid.Previews are the message's first
text/plainpart, or its firsttext/htmlpart 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 inlist_recent_emailsand 2000 insearch_emailsandget_thread.get_emaildownloads the complete message, including attachments, subject to a 20 MiB size limit, and returns up to 10000 characters.Attachments: contents are never returned;
attachmentslists 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 anattachmentdisposition 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.PEEKand 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.
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.
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 isYANDEX_OAUTH_LOOPBACK_PORT), and the permissionslogin:email,login:info,mail:imap_ro(reading mail) andmail: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 setYANDEX_OAUTH_CLIENT_SECRET, since token refresh has only been checked with it.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 loginA 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 sameYANDEX_OAUTH_CLIENT_ID(and secret, if one was used at login) in its environment.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'senvblock instead of a.envfile. 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).
Register a Yandex OAuth application as above, with the redirect URI
<MCP_PUBLIC_URL>/oauth/yandex/callback, for examplehttps://mail.example.com/oauth/yandex/callback. Note its client ID and client secret.Generate an encryption key:
python -c "import secrets, base64; print('k1:' + base64.urlsafe_b64encode(secrets.token_bytes(32)).decode())"In
.env, set:Variable
Value
MCP_PUBLIC_URLThe 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_KEYSThe generated key.
MCP_ALLOWED_USERSComma-separated Yandex logins or addresses allowed to sign in. Empty refuses everyone.
YANDEX_OAUTH_CLIENT_ID,YANDEX_OAUTH_CLIENT_SECRETThe application from step 1.
YANDEX_ALLOW_WRITEtrueto offer the changing tools; each user still has to grant full IMAP access.Start it with Docker Compose (
docker compose up -d --build), which binds127.0.0.1:8000on the host and keeps the registered clients in theauthvolume (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, replaceMCP_TOKEN_ENCRYPTION_KEYSwith a new key, which ends every token issued so far.Put an HTTPS reverse proxy in front of it. Without HTTPS, tokens travel in clear text. With Caddy, which obtains the certificate itself, a
Caddyfileof two lines is enough:mail.example.com reverse_proxy 127.0.0.1:8000Add 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/mcpto 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:
The operator enables changes with
YANDEX_ALLOW_WRITE=true. Without it the server never asks Yandex for more than read access and never offers themail.writescope.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 themail.writescope only when the user chose it and Yandex granted full access. A client that asks formail.readalone goes straight to read-only access and sees no page. On the local server,yandex-mail-mcp loginasks for full access whenYANDEX_ALLOW_WRITE=trueis set.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 raisesNoBackChannelError) is treated as one without it. On the shared HTTP server, such a client, or one without elicitation, gets a link instead: the tool returnsconfirmation_requiredwith aconfirm_urlon 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 withMCP_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:
The operator sets
YANDEX_ALLOW_WRITE=trueand restarts the server.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).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 beforeYANDEX_ALLOW_WRITE=true, or read only was chosen, or Yandex granted onlymail:imap_ro. Reconnecting alone does not help if the client reuses its refresh token; follow Upgrading a read-only connection.get_connection_capabilitiesshowsmcp_scopesandyandex_full_mail_accessfor 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.pyruns 20 read-only calls one after another and 20 at once against the configured mailbox and reports failures, response times and dropped sessions, then timesUID SEARCH ALLover the folder against the windowedFETCHthatlist_recent_emailsuses; 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_foldersshows 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 |
| empty | The Yandex OAuth application. Needed by |
| empty | Its secret. |
|
| Port of the |
| empty | A ready Yandex access token, used with |
| empty | The mailbox address, required with |
|
| IMAP server. |
|
| IMAP port, 1 to 65535; the connection always uses TLS. |
|
| 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. |
|
| Seconds an idle connection is kept before it is replaced. |
|
| Enables the changing tools. |
|
| Set to |
| empty | Destination of |
|
| Destination of the deprecated |
|
|
|
|
| HTTP bind address. |
|
| HTTP port, 1 to 65535. |
| empty | The HTTPS URL of the shared HTTP server; setting it turns on OAuth sign-in for several users. |
| empty |
|
| empty | Yandex logins or addresses allowed on the shared server, comma-separated. Empty refuses everyone. |
|
| SQLite file of the MCP clients registered with the shared server, the revoked sign-ins and the refresh generation of each sign-in. |
|
| Requests per client IP and minute to the sign-in and token endpoints. |
| empty | Proxies whose |
|
|
|
|
|
|
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
logouttool, 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_USERSdecides 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=trueon 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
loginin 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:latestThe 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=falseThe 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 srcuv 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 toolsget_emailARead-only
Read a message by IMAP UID, without marking it as read.
Inputs: uid (required), folder.
list_foldersARead-only
List IMAP folder names in the connected Yandex mailbox.
Inputs: no named parameters. Returns: result
list_recent_emailsARead-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_emailsCRead-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
Scored across 5 tools
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.
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.
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.
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
Related MCP Connectors
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
Email: search, read, fetch attachments; attach files when the MCP client supports inputs.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables 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
- FlicenseBqualityCmaintenanceEnables 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.303-
- FlicenseNot gradedqualityCmaintenanceEmail capabilities for AI agents to receive, read, reply, and send through MCP.-
- FlicenseNot gradedqualityCmaintenanceEnables MCP clients to access locally structured personal email data, with tools to list, search, retrieve emails and action items, and get mailbox statistics.-