exmail-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
exmail-mcp
An MCP server for Tencent Exmail (腾讯企业邮箱) mailboxes. It lets an AI agent search and read your mail safely, and send mail only through an explicit two-step draft → send flow that is easy to put behind human approval.
Read-only by default. Folders are opened with
EXAMINEand messages are fetched withBODY.PEEK, so nothing gets marked read. There are no delete / move / flag tools at all.Chinese works: RFC 2047 headers, raw GBK/GB2312/GB18030 headers and bodies, RFC 2231 filenames, and modified-UTF-7 folder names (e.g.
其他文件夹/客户).Incremental sync:
fetch_sincereturns everything newer than a UID in one IMAP session with batched fetches, plusuidvalidity/uidnextso a digest job can resume exactly where it stopped.Two-step sending:
create_draft(stored locally, returns a full preview) andsend_draft(sends that exact draft once) are separate tools. Every send is logged without its body.Runs anywhere: macOS, Windows and Linux, either natively with Python 3.11+ or in Docker (Docker Desktop on macOS/Windows). Two transports: stdio, and streamable HTTP with a bearer token.
Independent, unofficial project. Not affiliated with or endorsed by Tencent. Tencent Exmail only; it relies on Exmail-specific IMAP behaviour (see Known limits).
Contents: Choose an install · macOS · Windows · Linux · Configuration · Connecting a client · Tools · Safety model · Is it faster than plain IMAP/SMTP? · Known limits
Requirements
An Exmail account with IMAP/SMTP enabled. If your account uses a client-specific password (客户端专用密码), use that.
Outbound access to
imap.exmail.qq.com:993andsmtp.exmail.qq.com:465.Either Python 3.11 or newer (native install) or Docker (Docker Desktop on macOS and Windows, Docker Engine + Compose v2 on Linux).
Related MCP server: qq-email-mcp
Choose an install
Native Python | Docker | |
Best for | One person, MCP client on the same computer (Claude Desktop, Cursor, Claude Code) | An always-on machine serving several agents over a private network |
Transport | stdio (the client starts the server) or HTTP | HTTP (stdio via |
Secrets | Password + token files in your per-user config folder | Files on the host, mounted read-only |
Per-user default locations (native install). You can override every one of them, see Configuration.
OS | Config (password, token, contacts) | Data (drafts, logs, header cache, downloads, attachments) |
macOS |
|
|
Windows |
|
|
Linux |
|
|
Files in the config folder: exmail.pass (one line, the mailbox password only), mcp_token
(bearer token, only needed for HTTP), optional contacts.json.
macOS
Native Python (macOS)
# 1. Get the code and create a virtual environment (python.org or Homebrew Python 3.11+)
git clone https://github.com/wealllovegithub/exmail-mcp.git ~/exmail-mcp
cd ~/exmail-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
# 2. Password file, readable only by you
CFG="$HOME/Library/Application Support/exmail-mcp"
mkdir -p "$CFG" && chmod 700 "$CFG"
install -m 600 /dev/null "$CFG/exmail.pass"
open -e "$CFG/exmail.pass" # paste the password on one line, save, close
# 3. (HTTP only) bearer token
.venv/bin/python -c "import secrets;print(secrets.token_urlsafe(40))" > "$CFG/mcp_token"
chmod 600 "$CFG/mcp_token"
# 4. Try it
export EXMAIL_USER=you@example.com
.venv/bin/python server.py --stdio # stdio: waits for an MCP client on stdin; Ctrl+C to quit
.venv/bin/python server.py --port 8765 # HTTP on 127.0.0.1:8765
curl http://127.0.0.1:8765/healthz # -> okFor stdio you normally don't run it yourself: the MCP client starts it (see Connecting a client).
Run the HTTP server at login (optional, launchd). Save as
~/Library/LaunchAgents/com.example.exmail-mcp.plist, replacing YOU and the address:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
<key>Label</key><string>com.example.exmail-mcp</string>
<key>ProgramArguments</key><array>
<string>/Users/YOU/exmail-mcp/.venv/bin/python</string>
<string>/Users/YOU/exmail-mcp/server.py</string>
</array>
<key>EnvironmentVariables</key><dict>
<key>EXMAIL_USER</key><string>you@example.com</string>
</dict>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
<key>StandardErrorPath</key><string>/Users/YOU/Library/Logs/exmail-mcp.log</string>
</dict></plist>launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.exmail-mcp.plist
launchctl bootout gui/$(id -u)/com.example.exmail-mcp # to stop and unloadDocker Desktop (macOS)
git clone https://github.com/wealllovegithub/exmail-mcp.git ~/exmail-mcp && cd ~/exmail-mcp
cp .env.example .env # edit: EXMAIL_USER, EXMAIL_PASS_FILE, MCP_BIND_IP=127.0.0.1
mkdir -p secrets data downloads attachments config && chmod 700 secrets data
install -m 600 /dev/null ~/.exmail.pass && open -e ~/.exmail.pass # then EXMAIL_PASS_FILE=/Users/YOU/.exmail.pass
python3 -c "import secrets;print(secrets.token_urlsafe(40))" > secrets/mcp_token && chmod 600 secrets/mcp_token
docker compose up -d --build
curl http://127.0.0.1:8765/healthz # -> okrestart: unless-stopped brings it back whenever Docker Desktop starts. Enable Start Docker
Desktop when you sign in in Docker Desktop's settings to have it at login.
If the container can't read the password or token file, set RUN_UID/RUN_GID in .env to the
output of id -u / id -g.
Windows (PowerShell)
Native Python (Windows)
Install Python 3.11+ from python.org (tick Add python.exe to PATH) or winget install Python.Python.3.12.
# 1. Get the code and create a virtual environment
git clone https://github.com/wealllovegithub/exmail-mcp.git "$HOME\exmail-mcp"
Set-Location "$HOME\exmail-mcp"
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
# 2. Password file in %APPDATA%\exmail-mcp, readable only by you
$cfg = "$env:APPDATA\exmail-mcp"
New-Item -ItemType Directory -Force $cfg | Out-Null
notepad "$cfg\exmail.pass" # paste the password on one line, save, close
icacls "$cfg\exmail.pass" /inheritance:r /grant:r "${env:USERNAME}:(R,W)"
# 3. (HTTP only) bearer token
.\.venv\Scripts\python.exe -c "import secrets;print(secrets.token_urlsafe(40))" |
Out-File -Encoding ascii "$cfg\mcp_token"
icacls "$cfg\mcp_token" /inheritance:r /grant:r "${env:USERNAME}:(R,W)"
# 4. Try it
$env:EXMAIL_USER = "you@example.com" # this session only; use setx for a permanent value
.\.venv\Scripts\python.exe server.py --stdio # stdio: waits for an MCP client; Ctrl+C to quit
.\.venv\Scripts\python.exe server.py --port 8765
Invoke-WebRequest http://127.0.0.1:8765/healthz # -> okNotes: Notepad may save with a UTF-8 BOM; the server ignores it. If PowerShell blocks
Activate.ps1, you don't need it: call .venv\Scripts\python.exe directly as above.
Run the HTTP server at sign-in (optional, Task Scheduler). pythonw.exe runs without a
console window:
setx EXMAIL_USER you@example.com
$dir = "$HOME\exmail-mcp"
$action = New-ScheduledTaskAction -Execute "$dir\.venv\Scripts\pythonw.exe" -Argument "`"$dir\server.py`"" -WorkingDirectory $dir
$trigger = New-ScheduledTaskTrigger -AtLogOn -User $env:USERNAME
Register-ScheduledTask -TaskName "exmail-mcp" -Action $action -Trigger $trigger
# Remove later with: Unregister-ScheduledTask -TaskName exmail-mcpDocker Desktop (Windows)
git clone https://github.com/wealllovegithub/exmail-mcp.git "$HOME\exmail-mcp"
Set-Location "$HOME\exmail-mcp"
Copy-Item .env.example .env # edit: EXMAIL_USER, EXMAIL_PASS_FILE, MCP_BIND_IP=127.0.0.1
New-Item -ItemType Directory -Force secrets, data, downloads, attachments, config | Out-Null
notepad "$HOME\exmail.pass" # password on one line; then in .env:
# EXMAIL_PASS_FILE=C:/Users/YOU/exmail.pass (forward slashes)
python -c "import secrets;print(secrets.token_urlsafe(40))" | Out-File -Encoding ascii secrets\mcp_token
docker compose up -d --build
Invoke-WebRequest http://127.0.0.1:8765/healthzUse forward slashes (C:/Users/...) for paths in .env. Enable Start Docker Desktop when you
sign in to have it at login; the container restarts with Docker.
Linux
Native Python (Linux)
git clone https://github.com/wealllovegithub/exmail-mcp.git ~/exmail-mcp && cd ~/exmail-mcp
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt # Debian/Ubuntu: apt install python3-venv
CFG="${XDG_CONFIG_HOME:-$HOME/.config}/exmail-mcp"
mkdir -p "$CFG" && chmod 700 "$CFG"
install -m 600 /dev/null "$CFG/exmail.pass" && "${EDITOR:-nano}" "$CFG/exmail.pass"
.venv/bin/python -c "import secrets;print(secrets.token_urlsafe(40))" > "$CFG/mcp_token" && chmod 600 "$CFG/mcp_token"
EXMAIL_USER=you@example.com .venv/bin/python server.py --port 8765Run at boot/login (optional, systemd user service) – ~/.config/systemd/user/exmail-mcp.service:
[Unit]
Description=exmail-mcp
After=network-online.target
[Service]
Environment=EXMAIL_USER=you@example.com
ExecStart=%h/exmail-mcp/.venv/bin/python %h/exmail-mcp/server.py
Restart=on-failure
[Install]
WantedBy=default.targetsystemctl --user daemon-reload && systemctl --user enable --now exmail-mcp
loginctl enable-linger "$USER" # optional: keep it running when you are logged outDocker (Linux)
git clone https://github.com/wealllovegithub/exmail-mcp.git exmail-mcp && cd exmail-mcp
cp .env.example .env # then edit .env
mkdir -p secrets data downloads attachments config && chmod 700 secrets data
# optional: cp contacts.example.json config/contacts.json (name -> addresses, git-ignored)
install -m 600 /dev/null /path/to/exmail.pass && $EDITOR /path/to/exmail.pass # set EXMAIL_PASS_FILE to it
python3 -c "import secrets;print(secrets.token_urlsafe(40))" > secrets/mcp_token && chmod 600 secrets/mcp_token
docker compose up -d --build
curl http://<MCP_BIND_IP>:8765/healthz # -> okThe container runs as RUN_UID:RUN_GID (default 1000:1000), which must be able to read the
password and token files. Its root filesystem is read-only, it has no Linux capabilities, and the
password file is mounted read-only at /run/secrets/exmail.pass. restart: unless-stopped
starts it again after a reboot.
Configuration
All settings are environment variables. Native: set them in your shell, the service definition or the
MCP client's env block. Docker: put them in .env (copied from .env.example).
Variable | Meaning |
| Mailbox address (required) |
| Optional display name for the From header |
| Password file. Native default |
| Bearer token file (HTTP only). Native default |
| Native HTTP listen address and port (default |
| Docker only: host address to publish on. Use |
|
|
| IANA timezone for |
| Read-only connection pool size (default 3) and idle drop time (default 240 s) |
Locations (all optional; defaults shown for a native install):
Variable | Default |
| per-user config folder (table above) |
| per-user data folder (table above) |
|
|
|
|
|
|
|
|
| Docker only: host paths reported back to clients |
The Docker image sets /run/secrets/..., /data, /downloads, /attachments and
/config/contacts.json, which docker-compose.yml mounts from the host.
Advanced: EXMAIL_IMAP_HOST, EXMAIL_IMAP_PORT, EXMAIL_SMTP_HOST, EXMAIL_SMTP_PORT,
SENT_WAIT_SECONDS (20), SEARCH_SCAN_CAP (3000), HEADER_CACHE_MAX (50000),
DISK_HEADER_CACHE (on), WARM_HEADER_CACHE (on), MAX_ATTACH_BYTES (25 MB),
IMAP_POOL_NOOP_SECONDS (30).
Connecting a client
Two ways to connect:
stdio: the client starts
server.py --stdioitself. No network port, no token. Best when the client runs on the same computer as a native install.HTTP + bearer token: the server runs on its own (service or Docker); clients connect to
http://<host>:<port>/mcpwithAuthorization: Bearer <contents of the token file>. The server is stateless (JSON responses), so clients that sleep or reconnect often work fine.GET /healthzis the only unauthenticated path.
In the examples, replace the paths with yours. Python path: macOS/Linux
/Users/YOU/exmail-mcp/.venv/bin/python (or /home/YOU/...), Windows
C:\\Users\\YOU\\exmail-mcp\\.venv\\Scripts\\python.exe (JSON needs doubled backslashes, or use /).
Claude Desktop
Config file (Settings → Developer → Edit Config opens it):
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux: no official Claude Desktop build; use another client.
stdio (recommended):
{
"mcpServers": {
"exmail": {
"command": "/Users/YOU/exmail-mcp/.venv/bin/python",
"args": ["/Users/YOU/exmail-mcp/server.py", "--stdio"],
"env": { "EXMAIL_USER": "you@example.com" }
}
}
}Windows:
{
"mcpServers": {
"exmail": {
"command": "C:\\Users\\YOU\\exmail-mcp\\.venv\\Scripts\\python.exe",
"args": ["C:\\Users\\YOU\\exmail-mcp\\server.py", "--stdio"],
"env": { "EXMAIL_USER": "you@example.com" }
}
}
}HTTP + bearer: Claude Desktop's config file only launches local commands, so bridge with
mcp-remote (needs Node.js):
{
"mcpServers": {
"exmail": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://127.0.0.1:8765/mcp", "--allow-http",
"--header", "Authorization:${AUTH_HEADER}"],
"env": { "AUTH_HEADER": "Bearer <token>" }
}
}
}Restart Claude Desktop after editing.
Cursor
~/.cursor/mcp.json (all projects) or .cursor/mcp.json in a project (don't commit a token):
{
"mcpServers": {
"exmail": {
"command": "/Users/YOU/exmail-mcp/.venv/bin/python",
"args": ["/Users/YOU/exmail-mcp/server.py", "--stdio"],
"env": { "EXMAIL_USER": "you@example.com" }
},
"exmail-http": {
"url": "http://127.0.0.1:8765/mcp",
"headers": { "Authorization": "Bearer <token>" }
}
}
}(~/.cursor is %USERPROFILE%\.cursor on Windows.) Use one of the two entries.
Claude Code
# stdio (macOS/Linux)
claude mcp add exmail -e EXMAIL_USER=you@example.com -- ~/exmail-mcp/.venv/bin/python ~/exmail-mcp/server.py --stdio
# HTTP + bearer
claude mcp add --transport http exmail http://127.0.0.1:8765/mcp --header "Authorization: Bearer <token>"# stdio (Windows PowerShell)
claude mcp add exmail -e EXMAIL_USER=you@example.com -- "$HOME\exmail-mcp\.venv\Scripts\python.exe" "$HOME\exmail-mcp\server.py" --stdioAdd --scope user to make it available in every project. Check with claude mcp list.
Other MCP clients
stdio: command
<venv python>, args["<path>/server.py", "--stdio"], envEXMAIL_USER(plus any Configuration variables).stdio into Docker: command
docker, args["exec", "-i", "exmail-mcp", "python", "/app/server.py", "--stdio"]. On a remote host, wrap it in SSH:ssh user@your-server docker exec -i exmail-mcp python /app/server.py --stdio. stdio needs no token; access is controlled by SSH and Docker permissions.Streamable HTTP: URL
http://<host>:<port>/mcp, headerAuthorization: Bearer <token>.
Network and TLS
The server speaks plain HTTP and the bearer token travels in a header, so protect the transport:
Listen on
127.0.0.1when clients are on the same computer (the native default;MCP_BIND_IP=127.0.0.1for Docker).For other machines, use an encrypted overlay network address (Tailscale, WireGuard). Avoid plain LAN addresses on shared networks.
If clients must cross an untrusted network, put a TLS reverse proxy (Caddy, nginx, Traefik) in front and keep the server itself on
127.0.0.1.Never publish it on a public interface or port-forward it to the internet.
Treat the token like a password: keep the file private; rotate it by replacing the file and restarting the server.
Tools
Tool | What it does |
| Folder names (decoded), flags, delimiter; optional MESSAGES/UNSEEN via |
| Dates |
| Every message with UID > |
| Headers ( |
| Conversation by Message-ID / In-Reply-To / References across INBOX and Sent (or given folders), oldest first, with snippets or bodies. Bodies are fetched in batches per folder in one pooled session, text parts only. |
| Saves into the downloads directory; paths cannot escape it; never overwrites |
| Builds the message and stores it locally on the server host ( |
| Inspect stored drafts |
| Deletes an unsent local draft (files only). Refuses drafts that are |
| Sends email. Sends exactly the stored draft once, then ensures a copy is in Sent |
Incremental sync with fetch_since
Store uidvalidity and next_since_uid after each call. Next time call
fetch_since(since_uid=<stored>, uidvalidity=<stored>). While has_more is true, call again with the
new next_since_uid. If the server has reset UIDs, the response has uidvalidity_changed: true, starts
again from UID 0, and you should discard stored UIDs. Fetching uses BODY.PEEK and batched
UID FETCH ranges (headers, then BODYSTRUCTURE, then only the text parts plus each attachment's
small MIME header), so attachment bodies are never downloaded and messages stay unread.
Attachment names: Exmail's BODYSTRUCTURE re-encodes long attachment names and truncates them
(observed: cut to 30 bytes). So names are decoded from each attachment part's own MIME header
(BODY.PEEK[n.MIME]) with the same function get_message uses (Content-Disposition filename
first, then Content-Type name; RFC 2231 continuations and RFC 2047 encoded-words). Sizes from
BODYSTRUCTURE are estimates for base64 parts (size_approx: true).
Body text cleanup
Every tool that returns body text or snippets decodes leftover HTML entities (also double-escaped ones
such as &nbsp;), turns NBSP into a normal space, removes stray control characters and trailing
spaces, and collapses runs of blank lines into one.
Dates and time zones
Every message carries date (the raw header), date_iso (ISO 8601 in DISPLAY_TZ with offset, e.g.
2026-01-15T09:30:00+08:00 with DISPLAY_TZ=Asia/Shanghai) and date_utc (...Z). fetch_since/get_thread also give
internaldate_iso (when the server received the message); get_message gives internaldate_iso and
internaldate_utc in its headers. If the Date header is missing or broken,
the server's INTERNALDATE is used. Conversion uses zoneinfo explicitly, so the container's TZ
does not matter. Draft Date headers are written in DISPLAY_TZ.
Name matching (from_ / to)
A term matches an address entry when, after NFKC normalisation and case folding, it is a substring of:
the decoded display name (
张三 <...>), orthe email address;
for a Chinese name of 2+ characters, when the header entry has no display name, the pinyin of the name (
zhangsan, or given name + surnamesanzhang) is matched against the address's local part (separators ignored). This needspypinyin(included). Homophones can match;addresses listed for that name in the optional contacts file
contacts.json(CONTACTS_FILE; format incontacts.example.json; the real file is git-ignored).
matched_via reports which rule matched. Limit: if a header has no display name, the local part
isn't the name's pinyin, and the contacts file has no entry, a search by name cannot find it. Search
by address instead, or add a contacts entry.
Quoted history (strip_quotes)
get_message, get_thread and fetch_since accept strip_quotes=true. It cuts the text at the
first reply header (On ... wrote:, -----Original Message-----, -----原始邮件-----, QQ-style
------------------ 原始邮件 ------------------, 发件人:, 在 ... 写道:, or a From: line
followed by Sent:/Date:/To:/Subject:/发送时间: lines) and drops lines starting with >.
quotes_stripped says whether anything was removed. It's a heuristic: unusual client formats may
not be detected.
Connections and performance
Read tools share a small pool (IMAP_POOL_SIZE, default 3) of logged-in connections. Each
connection has a lock and serves one request at a time. Connections are only ever in read-only
(EXAMINE) state. Connections idle over 30 s are checked with NOOP, and ones idle longer than
IMAP_POOL_IDLE_SECONDS are closed. On a connection error the request reconnects and retries once
(reads are idempotent). Each tool call uses one session for all its work. Drafts (reply lookups) and
sending always open their own fresh connections. Headers are cached in memory per
folder + UIDVALIDITY + UID. A typical repeat call takes about 0.5–2 s instead of about 3 s, since the
~2.6 s login is skipped.
Safety model
Read-only reads. Every folder is opened with
EXAMINE; onlyBODY.PEEK[...],FLAGS,RFC822.SIZEand similar non-mutating fetch items are allowed. The IMAP wrapper raises onSTORE,COPY,MOVE,EXPUNGE,DELETE,RENAME,CREATE, non-peek fetches, andAPPEND(which is unlocked only insidesend_draftfor the Sent copy).Gate sending by tool name.
send_draftis the only tool that sends. Deny or require approval for it in your client and allow the rest.Send once. A draft is marked
sendingbefore SMTP starts, thensentorfailed. Any status other thandraftis refused, so a draft can never be sent twice and a failed send is never retried automatically. Bcc recipients are used for the envelope only, never written into headers.Send log.
SEND_LOG(send_log.jsonl) records timestamp, draft id, recipients, subject, Message-ID, result and Sent-copy outcome.DRAFT_LOG(draft_log.jsonl) records draft creation and deletion. No bodies, no secrets.Drafts are local. Drafts live in
DRAFT_DIRon the server host. Nothing is written to the mailbox untilsend_draft.delete_draftonly removes unsent local drafts.Secrets. The mailbox password is only read from its file at login time (mounted read-only in Docker) and is never logged or returned. The bearer token is compared in constant time. Keep both files private:
chmod 600on macOS/Linux,icacls ... /inheritance:ron Windows.Files. Downloads are confined to
DOWNLOAD_DIR, outgoing attachments toATTACH_DIR(mounted read-only in Docker);.., absolute paths and other drives are refused.Network. The native HTTP server listens on
127.0.0.1unless you changeMCP_HOST; see Network and TLS.
Is it faster than plain IMAP/SMTP?
Partly, and only after warm-up. It is IMAP and SMTP underneath, talking to the same Exmail
servers, so a cold fetch is not faster than a good IMAP client: Exmail needs roughly 50 ms per
message for header/BODYSTRUCTURE fetches and a login takes a couple of seconds.
Where it helps an agent:
Warm connection pool. Read tools reuse logged-in, read-only connections, so most calls skip the login. A typical repeat call took about 0.5–2 s instead of about 3 s in testing.
Header cache (memory and disk, per folder + UIDVALIDITY + UID). Thread and Message-ID lookups stop refetching headers; in testing a 4-message
get_threadwith bodies went from about 24 s to about 5 s.Search that works. Exmail's IMAP
SEARCHignores text criteria, so a plain IMAP script that relies on it silently gets every message back. This server filters on decoded headers instead.Fewer agent tokens. Compact structured JSON, decoded Chinese headers, HTML converted to text, entities cleaned and, with
strip_quotes, quoted reply history removed.
Measured in real use, including the MCP handshake: fetch_since took 3–5 s when there was no new
mail and 9–11 s for about 10 new messages with bodies. A first catch-up over a few hundred messages
can take tens of seconds. Numbers vary with mailbox size and network.
Why client-side text search?
Exmail's IMAP server ignores text criteria in SEARCH (FROM, SUBJECT, HEADER, TEXT and
CHARSET UTF-8 searches all return every message in the folder). Date and flag criteria
(SINCE, BEFORE, UNSEEN) do work. So the server narrows by date/flags on the server, then
matches from/to/subject on the decoded headers itself. Exmail also needs roughly 50 ms per message
for any header or BODYSTRUCTURE fetch, so headers are cached per folder + UIDVALIDITY + UID in
memory and on disk (HEADER_CACHE_DIR, private to the user; headers never change for a UID), and the
cache for INBOX and Sent is filled in the background after startup. Repeated searches, threads and
Message-ID lookups therefore do not refetch headers. Use since/before on large
folders; at most SEARCH_SCAN_CAP (default 3000) newest candidates are scanned per call.
Known limits
Tencent Exmail only. Defaults point at
imap.exmail.qq.com/smtp.exmail.qq.com, and the search, Sent-copy and filename handling are tuned to Exmail's IMAP quirks. Other servers are untested.Text search is client-side. Exmail's IMAP
SEARCHignores text criteria (FROM,SUBJECT,TEXT,CHARSET UTF-8), so only date/flag/UID narrowing happens on the server and from/to/subject are matched on decoded headers by this server. Usesince/beforeon large folders; at mostSEARCH_SCAN_CAPnewest candidates are scanned per call. Body text is not searchable.First-run cache warm-up. Exmail answers header/
BODYSTRUCTUREfetches at roughly 50 ms per message. On first start the server fills the header cache for INBOX and Sent in the background, which can take minutes on a large mailbox; the firstfetch_sincefrom UID 0 over a few hundred messages can take tens of seconds. Later calls hit the cache (HEADER_CACHE_DIR, can be disabled withDISK_HEADER_CACHE=off/WARM_HEADER_CACHE=off).Truncated filenames in
BODYSTRUCTURE. Exmail cuts long attachment names insideBODYSTRUCTURE(observed at 30 bytes), so the server reads names from each part's MIME header instead. Sizes for base64 parts are estimates (size_approx: true).Name search without display name. See Name matching: pinyin matching can hit homophones, and names whose address isn't their pinyin need a contacts entry.
Drafts are local, not in the mailbox Drafts (草稿) folder, so they don't appear in webmail.
No TLS in the server itself; see Network and TLS.
Platform testing. CI runs the offline tests on Linux, macOS and Windows. Live mailbox use has been exercised on Linux (Docker); native macOS/Windows service setups above are standard recipes but less battle-tested.
Tests
Offline tests need no network or mailbox and run on Linux, macOS and Windows (see
.github/workflows/ci.yml):
python -m venv .venv
.venv/bin/pip install -r requirements.txt # Windows: .venv\Scripts\pip ...
.venv/bin/python -m unittest discover -s tests -v # Windows: .venv\Scripts\python ...
.venv/bin/python tests/smoke_transports.py # starts stdio + HTTP (token) and lists toolsLive, read-only check against your mailbox (prints counts only, never sends, verifies the unread count is unchanged):
docker compose exec -T exmail-mcp python - < tests/live_readonly_check.py # Docker
EXMAIL_USER=you@example.com .venv/bin/python tests/live_readonly_check.py # nativeLicense
MIT. See LICENSE. Runtime dependencies are MIT (mcp, pydantic, anyio, pypinyin, platformdirs, ...), BSD-3-Clause (uvicorn, starlette, httpx, ...), Apache-2.0 (python-multipart, tzdata on Windows), PSF-2.0 and MPL-2.0 (certifi, used unmodified), all compatible with MIT.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Email for AI agents: read, search and send from your Gmail, Outlook, Yahoo, iCloud or IMAP inbox.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Give AI agents their own email inboxes: list, read and send mail via scoped, revocable OAuth grants.
Stateful email for AI agents: read inboxes, reply in-thread, draft with approval.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables AI agents to securely interact with Gmail and QQ Mail, including IMAP search/read/organization, attachments, and preview-confirmed sending.412MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI clients to read, search, manage, and send QQ mailbox emails via IMAP/SMTP, including attachments, drafts, replies, and structured message context for models.73 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to search and read email, inspect attachments, and optionally send messages and organize folders through existing IMAP and SMTP mailboxes. Supports Docker, stdio, and HTTPS OAuth deployment with read-only or full-access modes.MIT
- AlicenseNot gradedqualityBmaintenanceGives AI assistants OAuth-secured access to a single QQ Mail mailbox over IMAP and SMTP, letting them search, read, organize, draft, and send email with attachments. Supports folder management, flag changes, threaded replies, and forwarding through natural language.9 npmMIT