This MCP server enables AI agents to manage email via IMAP/SMTP across multiple accounts, supporting search, reading, sending, organizing, and attachment handling.
Search & Read (messages): Search using filters like UNREAD, FLAGGED, SINCE YYYY-MM-DD, FROM email, SUBJECT text, or combined queries; read individual emails by UID across one or all accounts.
Organize (messages): Mark emails as read/unread, flag/unflag, move to folders, archive, or trash — individually or in batch.
Send (send): Compose new emails with To/CC/BCC; reply (auto-maintains In-Reply-To/References threading headers, prepends "Re:"); forward (prepends "Fwd:", includes original body).
Folders (folders): List all mailbox folders (names, paths, flags) for one or all accounts.
Attachments (attachments): List attachments on a specific email or download them as base64-encoded content.
Multi-account: Manage Gmail, Outlook, Yahoo, iCloud, Zoho, ProtonMail, and custom IMAP accounts simultaneously via comma-separated credentials.
Auto-discovery: IMAP/SMTP settings are automatically detected from the email address domain.
Configuration (config): Set up, reset, and check credential status; supports app passwords and Outlook OAuth2 device-code flow.
Deployment: Runs in stdio mode for local single-user setups or HTTP mode for multi-user deployments with OAuth 2.1; supports Docker and Cloudflare serverless with encrypted token storage.
Help (help): Retrieve full documentation for any tool on demand.
Allows searching, reading, and sending emails through Gmail accounts using IMAP and SMTP protocols with support for App Passwords.
Provides tools for managing emails on iCloud and Me.com accounts, including searching, reading, sending, and organizing messages via IMAP/SMTP.
Enables interaction with ProtonMail accounts through the ProtonMail Bridge, supporting operations like searching, reading, and sending emails.
Supports email operations for Zoho Mail accounts, allowing users to search, read, send, and organize messages via IMAP and SMTP.
mcp-name: io.github.n24q02m/better-email-mcp
IMAP/SMTP email for AI agents -- read, send, organize folders, and manage attachments across multiple accounts, with auto-discovery.
Project | Tagline | Tag |
Peer AI agents chat in a shared folder — no human relay, no orchestrator, wor... | Tooling | |
Knowledge graph for token-efficient code reviews -- semantic search and call-... | MCP | |
2-way Google Drive sync with .driveignore filter — rclone engine, Windows tray | Tooling | |
IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att... | MCP | |
Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g... | MCP | |
Markdown-first Notion for AI agents -- pages, databases, blocks, and comments... | MCP | |
Drop-in python-semantic-release fork with built-in release-safety guards (orp... | Tooling | |
Telegram for AI agents -- messages, chats, media, and contacts across both bo... | MCP | |
Google Workspace MCP server (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch... | MCP | |
Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea... | Marketplace | |
Image and video understanding + generation for AI agents -- across Gemini, Op... | MCP | |
Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... | Tooling | |
Shared foundation for building MCP servers -- Streamable HTTP transport, OAut... | MCP | |
Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi... | MCP | |
Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF | Library | |
Secrets without the server. | CLI | |
A self-distilling neuro-symbolic cascade that amortises LLM cost across knowl... | Tooling | |
Shared web infrastructure package for search, scraping, HTTP security, and st... | Library | |
Open-source MCP server for AI agents: web search, content extraction, and lib... | MCP |
Related MCP server: WET - Web Extended Toolkit
Multi-account support -- manage 6+ email accounts (Gmail, Outlook, Yahoo, iCloud, Zoho, ProtonMail, custom IMAP)
App Passwords -- no OAuth2 setup required for most providers; clone and run in 1 minute
4 composite tools with 22 actions (plus help + config__open_relay) -- search, read, send, reply, forward, organize, and credential setup in single calls
Auto-discovery -- provider settings detected from email address, custom IMAP host supported
Thread-aware -- reply/forward maintains In-Reply-To and References headers
Tiered token optimization -- compressed descriptions + on-demand help tool + MCP Resources
The server runs in two modes: stdio (default, single-user, credentials from env vars) and HTTP (opt-in, multi-user with OAuth 2.1). For stdio, add it to your MCP client config:
{
"mcpServers": {
"better-email": {
"command": "npx",
"args": ["--yes", "@n24q02m/better-email-mcp@latest"],
"env": {
"EMAIL_CREDENTIALS": "user@gmail.com:app-password"
}
}
}
}Multiple accounts are comma-separated: user1@gmail.com:pass1,user2@outlook.com:pass2. See Configuration for all env vars, and Remote (HTTP Mode) to run a hosted multi-user server.
Most providers use an App Password (no OAuth setup); Outlook/Hotmail/Live use a bundled OAuth device-code flow in HTTP mode. Settings (IMAP/SMTP host, port) are auto-discovered from the email domain.
The package ships one binary, better-email-mcp (run via npx @n24q02m/better-email-mcp). With no arguments it starts the MCP server over stdio; it also accepts one flag and one subcommand:
Invocation | Description |
| Start the MCP server over stdio (default). Reads credentials from |
| Start the server in HTTP (multi-user, OAuth 2.1) mode. Equivalent to |
| Authenticate an Outlook/Hotmail/Live account via OAuth2 Device Code flow. Tokens are saved to |
| Clear the locally stored Outlook token(s). Omit |
# stdio server (normally launched by your MCP client, not by hand)
EMAIL_CREDENTIALS="user@gmail.com:app-password" npx @n24q02m/better-email-mcp
# HTTP multi-user server
npx @n24q02m/better-email-mcp --http
# One-off Outlook OAuth device-code sign-in
npx @n24q02m/better-email-mcp auth user@outlook.com
# Sign out of a single account (or omit the email to clear all)
npx @n24q02m/better-email-mcp logout user@outlook.comauth/logout are only for Outlook/Hotmail/Live addresses -- other providers use an App Password in EMAIL_CREDENTIALS. See Remote (HTTP Mode) for the HTTP config.
Published with a Smithery config (smithery.yaml). Smithery runs the server over stdio with no build config required; credentials are supplied at runtime through the server's own setup flow (see Configuration). The start command is:
startCommand:
type: stdio
commandFunction: |-
(config) => ({ command: 'npx', args: ['-y', '@n24q02m/better-email-mcp'] })Full docs at mcp.n24q02m.com/servers/better-email-mcp/setup/:
Setup -- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
Modes overview -- stdio (default) and HTTP (opt-in, multi-user with OAuth 2.1)
Multi-user setup -- per-JWT-sub credential model
Install with AI agent -- paste this to your AI coding agent:
Install MCP server
better-email-mcpfollowing the steps at https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-email-mcp/setup-with-agent.md
The public send tool is replaced by messages with action: new, reply, or forward.
This follows the MCP N+2 standard: sending is an action in the messages domain, so keeping a
separate send entry would duplicate that domain and add redundant tool-list and help-topic
surface. The old name is removed directly; there is no compatibility alias.
Old public name | New public name | Reason | Alias removal |
|
| N+2 domain-tool rule: outbound mail is part of the | Removed directly in the Unreleased release; no alias |
Tool | Actions | Description |
|
| Search, read, organize, compose, reply to, and forward emails |
|
| List mailbox folders or read targeted IMAP STATUS metadata |
|
| List and download email attachments |
|
| Credential setup via browser relay, status check, reset, re-resolve, cache clear |
| - | Open the relay configuration form in the browser and return the relay URL |
| - | Get full documentation for any tool |
URI | Description |
| Message operations reference |
| Folder operations reference |
| Attachment operations reference |
| Full documentation |
| Credential setup and runtime configuration reference |
How better-email-mcp stacks up against direct competitors in each pillar:
Capability | better-email-mcp | |||
IMAP/SMTP (provider-agnostic) | Yes | Yes | No (Gmail API only) | Yes |
Multi-account | Yes (comma-separated creds) | Yes | No (single global credential) | No (single account per instance) |
App Passwords | Yes (no OAuth setup) | Yes | No (OAuth2 only) | Yes |
Auto-discovery from email address | Yes | Yes (8 providers) | n/a (Gmail only) | No (manual host/port) |
Bundled Outlook OAuth (no user Azure app) | Yes (device-code, Thunderbird-pattern client) | partial (OAuth2 XOAUTH2, experimental) | No (user-supplied Google OAuth) | No |
Attachments (list + download) | Yes | Yes | Yes | Yes |
HTTP multi-user mode (per-JWT-sub) | Yes (OAuth 2.1, self-hostable) | No (stdio only) | No (stdio only) | No (stdio only) |
Run as a multi-user HTTP server with OAuth 2.1 authentication:
{
"mcpServers": {
"better-email": {
"type": "http",
"url": "https://<your-host>/mcp"
}
}
}Single multi-user mode (relay form for App-Password providers + bundled Outlook OAuth device-code):
docker run -p 8080:8080 \
-e PORT=8080 \
-e PUBLIC_URL=https://your-domain.com \
n24q02m/better-email-mcp:latestUsers provide their own email credentials through the OAuth flow / paste form. No server-side EMAIL_CREDENTIALS needed. With the default Docker self-host, per-user credentials are held in an in-memory store (cleared on restart); users re-submit after a restart. Outlook OAuth uses the bundled public Azure client (d56f8c71-9f7c-43f4-9934-be29cb6e77b0, Thunderbird-pattern) -- no user-side Azure app registration needed.
Self-hostable as a per-user serverless instance on Cloudflare Workers + Containers: each JWT sub
gets its own Container Durable Object, and all credentials AND Outlook OAuth tokens are
AES-256-GCM encrypted into Workers KV (one subs/<sub>/config blob per user) so they
survive scale-to-zero / container recreate with no re-auth. The JWT signing key is
derived deterministically from CREDENTIAL_SECRET (EdDSA), so the user's identity is
stable across recreate. Required secrets: CREDENTIAL_SECRET (per-sub vault + EdDSA),
MCP_RELAY_PASSWORD (form gate), MCP_DCR_SERVER_SECRET (intentional multi-user
deploy). See wrangler.jsonc.
Keying Outlook tokens by JWT
sub(in the per-sub KV blob) resolves the former email-keyedtokens.jsonambiguity (CLAUDE.md Known Bug #4): two users' Outlook accounts can no longer collide.
Caveat:
localhostIMAP accounts (email:pass:localhost:1993) are valid for local / VM deployments but CANNOT work on Cloudflare — there is no co-located IMAP proxy inside the container. Use a publicly-reachable IMAP host on CF.
In HTTP mode, Outlook/Hotmail/Live accounts use OAuth2 device-code automatically. On first use:
The server prints a device code and a Microsoft login URL
Open the URL in a browser and enter the code
Sign in and authorize the app
Tokens are persisted per JWT sub — in the encrypted Cloudflare KV credential blob (subs/<sub>/config) on the serverless deploy, in the local in-memory store for local HTTP, or in ~/.better-email-mcp/tokens.json for single-user / stdio
OAuth uses the bundled public Azure client (d56f8c71-9f7c-43f4-9934-be29cb6e77b0, Thunderbird-pattern) -- no user-side Azure registration needed.
In stdio mode, Outlook accounts use an App Password instead (Outlook Account Settings → Security → Advanced security options → App passwords).
To trust mise configuration automatically, set trusted_config_paths in the user-level config at ~/.config/mise/config.toml; do not add it to this project's .mise.toml.
Variable | Required | Default | Description |
| Yes (stdio) | - | Email credentials, |
| Alternative (stdio, single-account) | - | Email address. Used with |
| Alternative (stdio, single-account) | - | App password (Gmail/Yahoo/iCloud) or Outlook App Password; used with |
| No (http) | - | Server's public URL for relay / OAuth redirect links |
| No |
| Server port (http mode); set explicitly (e.g. |
| No | - | Bind address (http mode) |
| No (http) | - | Set to |
| No |
| Override the bundled Azure AD public client for self-hosted Outlook OAuth2 (or |
| No | - | Workaround when Microsoft device-code response omits the email field |
| No |
| Microsoft directory to sign in against, used for both the device-code and the token-refresh endpoint. Set |
| No |
| Space-separated scope list. Narrow it (e.g. drop |
| No | - | Comma-separated domains routed to OAuth in addition to |
EMAIL_CREDENTIALS=user1@gmail.com:pass1,user2@outlook.com:pass2,user3@yahoo.com:pass3# Custom hostname (default port 993, implicit TLS)
EMAIL_CREDENTIALS=user@custom.com:password:imap.custom.com
# Custom hostname with a custom port
EMAIL_CREDENTIALS=user@custom.com:password:imap.custom.com:1993
# Local IMAP proxy -- "localhost" is accepted as a host, even without a dot
EMAIL_CREDENTIALS=user@custom.com:password:localhost:1993Each account can use its own host and port. A non-993 port is treated as plaintext/STARTTLS -- the usual shape for a local IMAP proxy (for example email-oauth2-proxy).
A mailbox in a Microsoft 365 organisation -- including one on your own domain -- signs in through Entra ID rather than the consumer directory, and Microsoft disabled basic auth for Exchange Online in 2024, so an App Password is not an option. Two settings make it work:
# Sign in against the directory that owns the mailbox
OUTLOOK_TENANT=common # or a tenant GUID / verified domain
# Route your own domain to OAuth instead of asking for a password
OUTLOOK_EXTRA_DOMAINS=company.comOUTLOOK_TENANT applies to the token refresh as well as the initial sign-in --
refreshing a work/school token against the consumer directory fails with
AADSTS7000012: The grant was obtained for a different tenant.
If the mailbox was consented with a narrower grant (say IMAP but no SMTP), match
it with OUTLOOK_SCOPES so the refresh does not ask for more than was granted.
Query | Description |
| Unread emails |
| Starred emails |
| Emails after date |
| Emails from sender |
| Emails matching subject |
| Compound filter |
Provider | Auth | Save-to-Sent |
Gmail | App Password | Auto (skipped) |
Yahoo | App Password | Auto (skipped) |
iCloud/Me.com | App-Specific Password | Auto (skipped) |
Outlook/Hotmail/Live | OAuth2 (Device Code) | IMAP APPEND |
Zoho | App Password | IMAP APPEND |
ProtonMail | ProtonMail Bridge | IMAP APPEND |
Custom | Via | IMAP APPEND |
Credential sanitization -- Passwords never leaked in error messages
App Passwords -- Uses app-specific passwords, not regular passwords
Token storage -- Outlook OAuth tokens saved with 600 permissions
IMAP validation -- Search queries validated before execution
git clone https://github.com/n24q02m/better-email-mcp.git
cd better-email-mcp
bun install
bun run devRun your own multi-user better-email instance serverless on Cloudflare (Containers + KV).
Each JWT sub gets its own Container Durable Object, and every user's email credentials and
Outlook OAuth tokens are AES-256-GCM encrypted into a single Workers KV blob per user, so they
survive scale-to-zero / container recreate with no re-auth.
Prerequisites: a Cloudflare account on the Workers Paid plan — required for Containers (the Cloudflare free tier does not include Containers) — and the wrangler CLI.
git clone https://github.com/n24q02m/better-email-mcp && cd better-email-mcp
wrangler login
Create the KV namespace (better-email is KV-only -- no D1 / Vectorize):
wrangler kv namespace create better-email-kvPaste the returned id into <better-email-kv-namespace-id> in wrangler.jsonc.
Push the container image to your Cloudflare managed registry (CF Containers cannot pull
from external registries directly), then set <YOUR_ACCOUNT_ID> in wrangler.jsonc:
docker pull ghcr.io/n24q02m/better-email-mcp:beta
docker tag ghcr.io/n24q02m/better-email-mcp:beta better-email-mcp:beta
wrangler containers push better-email-mcp:beta # prints registry.cloudflare.com/<ACCOUNT_ID>/better-email-mcp:betaPoint wrangler.jsonc at your own domain: set <YOUR_PUBLIC_URL> (e.g.
https://email.example.com) and <YOUR_WORKER_DOMAIN> (e.g. email.example.com).
Set the deploy secrets:
wrangler secret put CREDENTIAL_SECRET # per-sub vault key + deterministic EdDSA signing (required)
wrangler secret put MCP_RELAY_PASSWORD # gate for the /authorize setup form
wrangler secret put MCP_DCR_SERVER_SECRET # proof of an intentional multi-user deployOptional Outlook overrides -- only to replace the bundled public Azure device-code client
(default needs no user-side Azure app): wrangler secret put OUTLOOK_CLIENT_ID and
wrangler secret put OUTLOOK_EMAIL. For a Microsoft 365 organisation, also set
OUTLOOK_TENANT (and OUTLOOK_EXTRA_DOMAINS for mailboxes on your own domain).
wrangler deploy, then open <YOUR_PUBLIC_URL>/authorize and complete the browser relay form.
End-users supply their own email credentials -- an App Password via the paste form, or the
bundled Outlook device-code sign-in -- through that relay form; there is no server-side
EMAIL_CREDENTIALS. Storage maps to Cloudflare via MCP_STORAGE_BACKEND=cf-kv (already set in
wrangler.jsonc); see Cloudflare serverless mode (KV-only)
for the encryption and trust details.
This plugin implements TC-NearZK. Storage durability depends on the deployment mode; see the mcp-core trust model for full classification.
Mode | Storage | Encryption | Who can read your data? |
HTTP remote (Cloudflare) | Encrypted Workers KV | AES-256-GCM | Server operator (admin = user) |
HTTP local Docker | In-memory | In-process only | Server process (cleared on restart) |
stdio | platformdirs | AES-GCM, machine-bound key | Only your OS user (file perm 0600) |
Apache-2.0 -- See LICENSE.
Email attachments: list, download. List shows all attachments for an email. Download returns base64-encoded content.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Action to perform | |
| account | Yes | Account email (required) | |
| uid | Yes | Email UID (required) | |
| folder | No | Mailbox folder (default: INBOX) | |
| filename | No | Attachment filename (required for download) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, non-destructive, and idempotent behavior, which the description does not contradict. The description adds valuable context beyond annotations by specifying that download returns 'base64-encoded content,' which is a key behavioral trait not covered by annotations. However, it does not mention rate limits or auth needs, which could be relevant.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and front-loaded, consisting of two efficient sentences that directly state the tool's actions and outcomes without any wasted words. Each sentence earns its place by clarifying the tool's functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (5 parameters, no output schema) and rich annotations, the description is mostly complete. It covers the core actions and output format for download, but could benefit from mentioning error cases or response structures for list actions. However, annotations provide safety context, making it adequate overall.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal semantic value beyond the schema by mentioning 'list shows all attachments for an email' and 'download returns base64-encoded content,' which loosely relates to parameters like 'action' and 'filename,' but does not provide additional details on parameter usage or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('list, download') and resource ('email attachments'), and distinguishes it from sibling tools like 'messages' or 'send' by focusing exclusively on attachment operations. It explicitly mentions what each action does: 'List shows all attachments for an email' and 'Download returns base64-encoded content.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying actions ('list' and 'download') and their outcomes, but does not explicitly state when to use this tool versus alternatives like 'messages' for general email handling. It provides some context (e.g., 'list shows all attachments for an email'), but lacks explicit guidance on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List mailbox folders for one or all email accounts. Returns folder names, paths, and flags.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Action to perform | |
| account | No | Account email filter (optional, defaults to all) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, non-destructive, and idempotent behavior, which the description doesn't contradict. The description adds value by specifying the return data ('folder names, paths, and flags'), which isn't covered by annotations, providing useful context about what information is retrieved. No rate limits or auth needs are mentioned, but annotations cover safety aspects adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently states the action, scope, and output without unnecessary words. It is front-loaded with the core purpose and avoids redundancy, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (list operation), rich annotations (read-only, idempotent), and full schema coverage, the description is mostly complete. It specifies output details, which compensates for the lack of an output schema. However, it could improve by mentioning any limitations (e.g., pagination) or error cases, though annotations provide good safety context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents both parameters (action and account). The description mentions 'one or all email accounts,' which aligns with the optional account parameter but doesn't add syntax or format details beyond what the schema provides. With high schema coverage, baseline 3 is appropriate as the description adds minimal extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('mailbox folders'), specifies scope ('for one or all email accounts'), and distinguishes from siblings like 'messages' or 'attachments' by focusing on folder metadata rather than message content. It provides specific output details ('folder names, paths, and flags') that further clarify its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying it works for 'one or all email accounts,' which helps differentiate from tools that might target specific accounts only. However, it lacks explicit guidance on when to use this versus alternatives like 'messages' (which might list messages within folders) or any prerequisites for accessing accounts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full documentation for a tool. Use when compressed descriptions are insufficient.
| Name | Required | Description | Default |
|---|---|---|---|
| tool_name | Yes | Tool to get documentation for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable context beyond what annotations provide. While annotations indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description clarifies that this tool provides 'full documentation' when regular descriptions are insufficient. This adds meaningful behavioral context about the tool's purpose and output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences that each serve distinct purposes: the first states what the tool does, the second provides usage guidance. There's zero wasted language and it's front-loaded with the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple purpose (retrieving documentation), single parameter with full schema coverage, and comprehensive annotations, the description is mostly complete. However, it doesn't describe what format the 'full documentation' returns (e.g., markdown, HTML, plain text), which would be helpful since there's no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the input schema already fully documents the single parameter 'tool_name' with its enum values. The description doesn't add any additional parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Get full documentation') and resource ('for a tool'), distinguishing it from sibling tools like 'messages', 'folders', 'attachments', and 'send' which perform different operations. It explicitly defines its unique purpose in the tool ecosystem.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: 'Use when compressed descriptions are insufficient.' This clearly differentiates it from the default tool descriptions and provides a specific trigger condition for its usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Email messages: search, read, mark_read, mark_unread, flag, unflag, move, archive, trash. Search across all accounts or filter by account. Query supports: UNREAD, FLAGGED, SINCE YYYY-MM-DD, FROM x, SUBJECT x.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Action to perform | |
| account | No | Account email filter (optional, defaults to all for search) | |
| query | No | Search query: UNREAD, FLAGGED, SINCE YYYY-MM-DD, FROM email, SUBJECT text, or combined (default: UNSEEN) | |
| folder | No | Mailbox folder (default: INBOX) | |
| limit | No | Max results for search (default: 20) | |
| uid | No | Email UID (for read/modify single email) | |
| uids | No | Multiple UIDs for batch operations | |
| destination | No | Target folder for move action |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover basic hints (readOnlyHint: false, destructiveHint: false, etc.), so the description adds value by detailing specific actions and query syntax. However, it doesn't disclose additional behavioral traits like rate limits, authentication needs, or error handling beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with key actions, though it could be more structured (e.g., separating action types). Every sentence adds value, but minor improvements in organization could enhance clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 8 parameters, no output schema, and annotations covering basic hints, the description is adequate but incomplete. It lacks details on return values, error cases, or prerequisites, leaving gaps for an AI agent to fully understand tool behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents parameters. The description adds minimal semantics by listing actions and query examples, but doesn't provide significant meaning beyond what's in the schema, aligning with the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool handles email messages with specific actions (search, read, mark_read, etc.), which is a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'attachments' or 'folders', though the domain focus is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through action enumeration and query examples, but doesn't provide explicit guidance on when to use this tool versus alternatives like 'send' or 'attachments'. It mentions filtering by account, which offers some context, but lacks clear when/when-not directives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send emails: new, reply, forward. Reply maintains thread headers (In-Reply-To, References) and auto-prepends "Re:" to subject. Forward includes original body and auto-prepends "Fwd:" to subject.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Action to perform | |
| account | Yes | Sender account email (required) | |
| to | No | Recipient email address (required for new/forward, optional for reply - auto-derived from original sender) | |
| subject | No | Email subject (required for new) | |
| body | Yes | Email body text (required) | |
| cc | No | CC recipients (comma-separated) | |
| bcc | No | BCC recipients (comma-separated) | |
| uid | No | Original email UID (required for reply/forward) | |
| folder | No | Folder of original email (default: INBOX) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide key behavioral hints (readOnlyHint=false, destructiveHint=false, etc.), and the description adds useful context beyond this, such as how reply and forward actions handle subject lines and thread headers. However, it lacks details on potential side effects, error conditions, or rate limits, which would enhance transparency further.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured, using two sentences that efficiently cover the tool's actions and key behavioral details without redundancy. Every sentence adds value, making it easy to understand at a glance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, no output schema) and rich annotations, the description is mostly complete, covering core functionality and behavioral traits. However, it could be more comprehensive by including information on error handling or response formats, which would improve completeness for a tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the input schema already documents all parameters thoroughly. The description adds minimal semantic value by mentioning 'reply maintains thread headers' and 'forward includes original body', but does not elaborate on parameter interactions or usage nuances beyond what the schema provides, aligning with the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('send emails: new, reply, forward') and distinguishes it from sibling tools like 'attachments', 'folders', 'help', and 'messages' by focusing exclusively on email sending functionality. It provides concrete details about how reply and forward actions work, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly guides usage by explaining the differences between 'new', 'reply', and 'forward' actions, including how reply maintains thread headers and auto-prepends 'Re:', and forward includes original body and auto-prepends 'Fwd:'. However, it does not explicitly state when to use this tool versus alternatives or mention any exclusions, which prevents a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose with no overlap: attachments handles attachments, folders manages mailbox folders, help provides documentation, messages handles email messages, and send sends emails. The descriptions clearly separate their domains, making misselection unlikely.
All tool names follow a consistent snake_case pattern using plural nouns (attachments, folders, messages) or verbs (help, send). This predictable naming scheme makes the tool set easy to navigate and understand.
With 5 tools, this server is well-scoped for email management. Each tool earns its place by covering distinct aspects: folder management, message handling, sending, attachments, and help. The count is neither too thin nor overwhelming for the domain.
The tool set provides comprehensive coverage for core email workflows: reading, searching, organizing, sending, and managing attachments. A minor gap exists in lacking explicit tools for account management (e.g., adding/removing accounts) or advanced message operations like deleting permanently, but agents can work around this with existing tools.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Read, search, send, organize, draft and schedule email across your inboxes from any MCP client.
Read, send, file and search email in any IMAP or Microsoft 365 mailbox, and check it arrived.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Read, send and organize email and calendars on any IMAP/CalDAV mailbox: OVH, iCloud, Zoho, Fastmail.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/n24q02m/better-email-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
