email-mcp

Small personal MCP server for a single mailbox over IMAP + SMTP.

It is aimed at a private setup first:

• one mailbox

• credentials supplied through environment variables

• read mail over IMAP

• send mail over SMTP

• works well with Yandex Mail defaults, but can be pointed at any IMAP/SMTP provider

What I changed

This repo originally worked only in stdio mode. That is fine for local MCP clients, but ChatGPT web integration needs an HTTP MCP endpoint. The server now supports:

• stdio for local/dev use

• streamable-http for ChatGPT web app use

• sse for compatibility

I also fixed a mail-threading issue:

• the old reply_to parameter only set the Reply-To header

• real replies should usually use In-Reply-To and References

• read_email now returns those headers so they can be passed back into send_email

And I improved read_email output by returning:

• decoded headers

• attachment metadata

• message threading headers

Related MCP server: IMAP/SMTP Email MCP Server

Attachment support

This version supports both reading and sending attachments.

Download an attachment from a received email

1. Call read_email(uid=..., folder="INBOX")

2. Inspect the attachments list

3. For a remote MCP, call:

create_attachment_download(
  uid=123,
  folder="INBOX",
  attachment_index=0
)

It returns a download_url valid for 15 minutes and one successful GET:

curl.exe --location `
  --output "report.xlsx" `
  "https://mail.example.com/attachments/download/dwl_..."

The response includes the original content type and an RFC 5987 encoded filename. It uses Cache-Control: no-store; the token is consumed by the first successful request. The attachment bytes do not pass through model context.

For very small attachments, get_attachment(...) remains available. Use its attachment_index or filename.

get_attachment(...) returns:

• filename

• content_type

• size_bytes

• content_base64

Send attachments in outgoing email

send_email(...) accepts an attachments list.

When the MCP server runs on another machine, upload the local file first.

For Codex, the recommended method sends raw bytes directly over HTTPS without printing base64 or putting it into model context:

1. Call:

create_attachment_upload(
  filename="report.xlsx",
  size_bytes=55455,
  content_type="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  sha256="optional lowercase SHA-256"
)

2. Use its upload_url and upload_token from the local shell:

curl.exe --request PUT `
  --header "Authorization: Bearer <upload_token>" `
  --header "Content-Type: application/octet-stream" `
  --data-binary "@G:\path\report.xlsx" `
  "https://mail.example.com/attachments/upload"

The response contains attachment_id. The upload session is single-use and expires after 15 minutes. File bytes travel directly from the local HTTP client to the remote MCP server and never pass through model output.

Configure the remote server's public HTTPS origin:

MCP_PUBLIC_BASE_URL=https://mail.example.com

Use the origin only, without the MCP endpoint path such as /mcp. The reverse proxy must forward /attachments/upload to this application, allow PUT, and permit request bodies up to the configured attachment limit.

For very small files, base64 upload remains available:

upload_attachment(
  filename="report.xlsx",
  content_base64="...",
  content_type="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  sha256="optional lowercase SHA-256"
)

The result contains an opaque attachment_id. Pass it to send_email, reply_to_email, or create_draft:

{"attachment_id": "att_..."}

Uploads are stored temporarily on the MCP server and expire after 24 hours. Use delete_attachment(attachment_id) to remove one earlier. Local filesystem paths refer to the MCP server machine and must not be used for files that exist only on the ChatGPT/Codex machine.

The default decoded-file limit is 5 MiB per attachment, with a 10 MiB combined attachment limit per message. Base64 is approximately 33% larger than the decoded file. Limits can be configured with:

MAIL_ATTACHMENT_MAX_BYTES=5242880
MAIL_ATTACHMENT_TOTAL_MAX_BYTES=10485760
MAIL_ATTACHMENT_DIR=/var/lib/email-mcp/attachments

For a local MCP process that shares the filesystem, an item can also use:

{"path": "/path/to/file.pdf"}

{"filename": "note.txt", "content_text": "hello from MCP"}

{"filename": "report.pdf", "content_base64": "JVBERi0x...", "content_type": "application/pdf"}

Sent folder behavior

After SMTP send succeeds, the same MIME message is appended to your IMAP sent folder.

By default that folder name is:

Sent

You can override it if your mailbox uses a different IMAP folder name:

export SENT_FOLDER="Sent"
# or
export MAILBOX_SENT_FOLDER="Sent"

If sent mail does not show up, first run list_folders() and use the exact folder name returned by your mailbox.

Files

• server.py — MCP tool definitions and transport startup

• mail_ops.py — IMAP/SMTP implementation

• requirements.txt — Python dependencies

Environment

Required:

export MAILBOX_EMAIL="you@example.com"
export MAILBOX_PASSWORD="your-app-password"

For local development, you can instead create a .env file beside server.py:

MAILBOX_EMAIL=you@example.com
MAILBOX_PASSWORD=your-app-password

The .env file is ignored by Git. Environment variables already supplied to the process take precedence over values in .env.

Optional provider settings:

export IMAP_HOST="imap.yandex.com"
export IMAP_PORT="993"
export SMTP_HOST="smtp.yandex.com"
export SMTP_PORT="465"

Optional sent-folder setting:

export SENT_FOLDER="Sent"

Optional MCP server settings:

export MCP_TRANSPORT="stdio"
export MCP_HOST="0.0.0.0"
export MCP_PORT="8000"

Aliases also supported for convenience:

export YANDEX_EMAIL="you@yandex.ru"
export YANDEX_APP_PASSWORD="..."

Install

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run locally with stdio

python server.py

This is the right mode for local MCP clients that spawn the process directly.

Run for ChatGPT web app

ChatGPT web needs a public HTTPS MCP endpoint. Start the server in HTTP mode:

python server.py --transport streamable-http --host 0.0.0.0 --port 8000

Then expose that port through a public HTTPS tunnel or reverse proxy, and register the resulting MCP URL in ChatGPT.

Tools exposed

Health and folders

• get_status() checks IMAP and SMTP authentication without sending mail.

• list_folders() returns provider folder names and special-use flags.

• create_attachment_upload() prepares a direct binary upload that bypasses model context.

• create_attachment_download() returns a short-lived, single-use binary URL for a received attachment.

• upload_attachment() transfers a small file to temporary remote storage.

• delete_attachment() removes a temporary upload.

list_folders()

Lists available IMAP folders.

search_emails(folder="INBOX", text=None, unseen_only=False, since_date=None, limit=30)

Searches messages by IMAP criteria.

Returns items like:

• uid

• subject

• from

• to

• date

• flags

• size_bytes

read_email(uid, folder="INBOX")

Fetches a full message without marking it read.

Returns:

• decoded headers

• message_id

• in_reply_to

• references

• attachments

• body_plain

• body_html

get_attachment(uid, folder="INBOX", attachment_index=None, filename=None)

Fetches a single attachment and returns it as base64.

send_email(...)

Sends a message through SMTP.

Important parameters:

• reply_to_header — sets the Reply-To header

• in_reply_to — threading header

• references — threading header

• attachments — optional list of attachment specs

For a real reply, use in_reply_to and usually also references.

Supply a unique idempotency_key for every logical send. Results distinguish sent, sent_but_not_saved, failed_before_send, and delivery_uncertain, and include safe_to_retry.

Mailbox-wide retrieval

• search_mailbox(...) searches Inbox, Sent, and Archive by default with structured participant, subject, body, and date filters.

• read_emails(...) batch-reads up to 50 results.

• search_threads(...) groups matching messages across folders.

• read_thread(...) reads an RFC-header-based thread chronologically.

• find_correspondents(...) resolves people from parsed address headers.

• find_sent_examples(...) returns cleaned authored text for style analysis.

Replies and drafts

• reply_to_email(...) derives recipients and RFC thread headers.

• create_draft(...), list_drafts(...), read_draft(...), update_draft(...), send_draft(...), and delete_draft(...) provide a review-before-send workflow.

Local search index

sync_search_index(...) incrementally indexes normal mailbox folders into the Git-ignored .mail_index.sqlite3 database. Synchronization tracks folder UIDVALIDITY and the last indexed UID.

search_index(...) performs ranked Unicode FTS5 retrieval with snippets. Its optional approximate mode broadens words into local prefix alternatives. No message content is sent to an external embedding service.

Yandex notes

Typical Yandex defaults are:

• IMAP: imap.yandex.com:993 over SSL/TLS

• SMTP: smtp.yandex.com:465 over SSL/TLS

Use an app password, not your main account password.

Tests

Run the offline test suite with:

python -m pytest

The suite covers structured errors, special folders, idempotent and partial sending states, Unicode search construction, pagination, reply headers, thread grouping, drafts, MIME body cleaning, and local FTS synchronization.