metu-webmail-mcp
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., "@metu-webmail-mcpCheck my inbox for unread emails from my advisor."
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.
METU Webmail MCP Server π¨
A Model Context Protocol (MCP) server for Middle East Technical University (METU / ODTΓ) Webmail (https://webmail.metu.edu.tr).
Connect your AI assistants (Claude Desktop, Cursor, Antigravity, OpenCode, etc.) to your METU email account to list, search, read, send, reply to, flag, and organize emails securely using METU's official IMAP and SMTP servers.
β¨ Features
π₯ Inbox & Folder Management: List all mailboxes (
INBOX,Sent,Drafts,Trash, custom folders) and check unread message counts.π Advanced Email Search: Filter messages by keyword query, sender, recipient, subject, date ranges (
SINCE,BEFORE), and read/flagged status.π Clean Content Reading: Robust RFC2047 decoding for Turkish characters (UTF-8, ISO-8859-9, windows-1254), automatic HTML to clean Markdown conversion, and message threading metadata.
π Attachment Support: Inspect attachment metadata and download/extract file attachments.
βοΈ Send, Reply & Forward: Send new emails via SMTP (with automatic save to
Sent), reply with automatic threading headers (In-Reply-To,References,Re:prefix), and forward messages.π·οΈ Flag & Organize: Mark emails as read/unread or starred/flagged, and move or delete messages.
π Dual Transport: Supports standard MCP
stdiomode andsseHTTP streaming mode.
Related MCP server: mcp-imap
π οΈ Installation & Setup
Prerequisites
Python 3.11+
uv(recommended) orpip
1. Clone & Install Dependencies
cd /Users/ates/Documents/projects/metu-webmail-mcp
uv sync2. Configure Credentials
Create a .env file in the project root:
METU_USERNAME=e123456@metu.edu.tr
METU_PASSWORD=your_metu_password
# Optional configurations (defaults shown)
METU_IMAP_SERVER=imap.metu.edu.tr
METU_IMAP_PORT=993
METU_SMTP_SERVER=smtp.metu.edu.tr
METU_SMTP_PORT=587Note: Both
METU_USERNAME/METU_PASSWORDandSAIS_USERNAME/SAIS_PASSWORDare automatically supported.
π€ MCP Client Configuration
Claude Desktop / Antigravity / Cursor
Add the following to your MCP client configuration (claude_desktop_config.json or equivalent):
{
"mcpServers": {
"metu-webmail": {
"command": "uv",
"args": [
"--directory",
"/Users/ates/Documents/projects/metu-webmail-mcp",
"run",
"metu-webmail-mcp"
],
"env": {
"METU_USERNAME": "e123456@metu.edu.tr",
"METU_PASSWORD": "your_password"
}
}
}
}π§° Available Tools
Tool | Description |
| Returns overall account summary, email address, all folder metrics, and total unread count. |
| Lists all mailbox folders with total and unread email counts. |
| Lists recent emails from a folder (e.g. |
| Searches emails by text query, sender, recipient, subject, date ranges, unread only, or flagged only. |
| Reads full email content, decoded headers, markdown/html body, attachments list, and optionally marks as read. |
| Downloads/extracts attachment base64 content by filename or index. |
| Sends an email via METU SMTP with optional HTML body, CC, BCC, and file attachments. |
| Replies to an existing email with automatic message threading and quoting. |
| Forwards an existing email with optional comments to new recipients. |
| Updates flags (read/unread, flagged/starred). |
| Moves an email from one folder to another. |
| Moves an email to Trash or permanently deletes it. |
π§ͺ Testing
Run unit and integration tests:
uv run pytest -vπ License
MIT License.
Available Tools
12 toolsdelete_emailC
Delete an email message.
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | The folder containing the email (default: 'INBOX'). | INBOX |
| permanent | No | If True, permanently expunges the message. If False (default), moves it to Trash. | |
| message_id | Yes | The ID of the email to delete. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure, and it delivers almost nothing. It does not say the default action moves to Trash rather than deleting permanently, nor whether the operation is reversible or requires special permissions β the only signal on that comes from the schema's parameter descriptions.
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 single sentence is front-loaded and free of waste, but for a destructive, multi-parameter tool with no annotations it is under-specified rather than genuinely concise. The brevity leaves useful context unstated.
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?
An output schema exists, so return values need not be explained, and the schema fully documents all three parameters. What remains thin is the description's coverage of the destructive semantics and the absence of any guidance against sibling tools, leaving completeness merely adequate.
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%, and the schema already documents message_id, folder (default 'INBOX'), and permanent (trash vs. expunge) thoroughly. The description adds no parameter meaning beyond that, which is the expected baseline when the schema does the heavy lifting.
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?
States a specific verb and resource ('Delete an email message'), so the agent knows exactly what operation this performs. However, it offers no differentiation from siblings like move_email, which can also remove a message from a folder, leaving the agent to infer the distinction.
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?
There is no guidance on when to use this versus alternatives such as move_email, nor any mention of prerequisites or the trash-vs-permanent decision at the usage level. The agent must derive the workflow entirely from the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
forward_emailC
Forward an existing email to new recipient(s).
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | New recipient email address or list of addresses. | |
| folder | No | The folder where the original email is located (default: 'INBOX'). | INBOX |
| message_id | Yes | The ID of the email to forward. | |
| attachments | No | Optional additional file paths to attach. | |
| additional_message | No | Optional note or comment to precede the forwarded message. |
Output Schema
| Name | Required | Description |
|---|---|---|
| message | Yes | Status description message |
| success | Yes | Whether sending succeeded |
| message_id | No | Generated Message-ID |
| recipients | No | List of recipient addresses |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'Forward' implies a send/mutation, but there is no disclosure of permissions, side effects, whether the original sender is visible, or what new message gets created.
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?
A single front-loaded sentence with no wasted words. It is appropriately sized for a simple action, though it borders on under-specification rather than over-verbosity.
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?
The tool is simple and has an output schema, so return values need not be explained. However, with no annotations and no usage or behavioral context, the description leaves gaps for a mutation tool that sends email; it is minimally adequate but not fully complete.
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 parameters (message_id, to, folder, attachments, additional_message) are fully documented in the schema. The description adds no parameter details beyond what the schema already provides, making the baseline 3 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?
States a specific verb (Forward) and resource (existing email) with target (new recipients). It is clear and distinct from send_email and reply_email by implication, but it does not explicitly distinguish itself from siblings or name alternatives.
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?
No when-to-use guidance or alternatives are given. An agent can infer it is for forwarding, but the description does not say when to prefer it over send_email/reply_email or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_attachmentB
Download/extract an attachment from an email message.
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | The folder containing the email (default: 'INBOX'). | INBOX |
| message_id | Yes | The ID of the email message. | |
| attachment_name_or_index | Yes | The filename (e.g. 'syllabus.pdf') or part index number of the attachment. |
Output Schema
| Name | Required | Description |
|---|---|---|
| filename | Yes | Name of the attached file |
| part_index | No | Index of MIME part |
| size_bytes | No | Size of attachment in bytes |
| content_type | Yes | MIME type of the attachment |
| content_base64 | No | Base64 encoded content (only if requested) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Download/extract' implies a read operation, but nothing is said about authentication needs, attachment size limits, what happens with multiple matches, or how the payload is delivered (binary vs. saved file), which matters for a download tool.
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?
A single front-loaded sentence with the action verb and resource stated first and zero wasted words. Appropriate length for a simple retrieval tool.
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?
An output schema exists, so return values need not be explained, and the schema fully covers parameters. However, for a tool requiring a message_id that must be sourced elsewhere, the absence of any prerequisite or workflow guidance leaves a small but real gap.
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%, and all three parameters (folder, message_id, attachment_name_or_index) are documented in the schema itself. The description adds no extra meaning beyond the schema, so the baseline 3 applies.
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 states a specific verb ('download/extract') and resource ('attachment from an email message'), which cleanly separates it from every sibling, none of which deal with attachments. It stops short of a 5 only because it doesn't contrast itself with alternatives (e.g. read_email) the way a maximally differentiated definition would.
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?
There is no when-to-use guidance, no prerequisites (e.g. that a message_id must first be obtained via list_emails/search_emails), and no stated alternatives. The usage is only vaguely implied by the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_mailbox_statusA
Get the overall status of your METU Webmail account.
Returns the user's email address, list of all mailbox folders (Inbox, Sent, Drafts, Trash), message counts, and the total number of unread emails.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| Yes | Full METU email address | |
| folders | No | List of mailboxes |
| username | Yes | METU user account |
| total_unread | No | Total unread messages across all folders |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. The verb "Get" implies a read-only summary and the content enumeration is benign, but permissions, auth requirements, and side effects are never addressed beyond the implicit safe-read framing.
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?
Two sentences, front-loaded with the verb and resource, then the return contents. No filler or repetition; every clause earns its place.
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?
For a zero-parameter status tool with an output schema present, the description is essentially sufficientβreturn fields are even summarized, which the output schema would cover anyway. Only the absent usage framing keeps it from being fully complete.
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?
The schema declares zero parameters, so per the baseline rule there is nothing for the description to compensate for. No parameter-level ambiguity exists.
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?
States a specific verb and resource ("Get the overall status of your METU Webmail account") and enumerates the returned content, which implicitly separates it from the granular siblings list_folders/list_emails. It is clear what it does, though it never names an alternative to sharpen the boundary.
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?
There is no when-to-use guidance, no prerequisites, and no reference to alternatives such as list_folders or list_emails. An agent can infer this is an account-overview call, but nothing in the text tells it when this is preferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_emailsC
List recent emails from a specific mailbox folder.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of emails to retrieve (default: 20, max recommended: 50). | |
| folder | No | Mailbox name to list emails from (e.g. 'INBOX', 'Sent', 'Drafts'). Default is 'INBOX'. | INBOX |
| offset | No | Offset for pagination (default: 0). | |
| unread_only | No | If True, only returns unread emails. Default is False. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'Recent' is the only behavioral hint and it is undefined (how recent? sorted how?). Nothing is said about pagination behavior, permissions, rate limits, or ordering, which matters for a listing tool with offset/limit parameters.
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?
A single clean sentence with the action front-loaded and zero filler. It is efficient, though its brevity contributes to the thin guidance elsewhere.
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?
With a full output schema, return values need not be explained, and the 100%-covered input schema handles parameters. The remaining gap is routing guidance relative to search_emails and read_email, which the description never addresses.
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 limit, folder, offset, and unread_only in detail. The description adds no semantics beyond what the schema provides, so the baseline 3 applies.
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 uses a specific verb (List) and resource (emails) and scopes it to a mailbox folder, so the core action is unambiguous. However, it does not distinguish itself from the closely related siblings search_emails or read_email, leaving the agent to infer the boundary.
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?
There is no guidance on when to use this versus search_emails (filtered query) or list_folders, nor any stated prerequisites or exclusions. Usage is only implied by the phrase 'recent emails from a specific mailbox folder'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_foldersB
List all available email folders and mailboxes in your METU Webmail account.
Returns folder names, user-friendly labels, and total/unread message counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden; it implies a side-effect-free read via 'List all available' but never states it explicitly, and says nothing about permissions or whether folders can change between calls. For a trivial no-parameter read, the implied semantics are adequate, but it stops short of explicit behavioral disclosure.
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?
Two short sentences, front-loaded with the action and resource. The second sentence enumerates return fields that the existing output schema already covers, making it mildly redundant rather than wasteful.
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?
An output schema exists, so the description need not explain return values, and for a zero-parameter read tool this is close to complete. The only real gap is the missing when-to-use versus the sibling mailbox-status/listing tools.
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?
The tool takes zero parameters, so there is no parameter semantics to convey and the baseline is 4. The schema coverage is 100% and the empty schema matches the description's claim of a full listing.
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?
Names a specific verb and resource ('List all available email folders and mailboxes') and scopes it to a METU Webmail account, so the agent knows exactly what it retrieves. It does not distinguish itself from nearby siblings like get_mailbox_status, which a zero-param folder lister plausibly overlaps with, but the core purpose is 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 never says when to call this versus get_mailbox_status, list_emails, or search_emails, nor does it state any precondition. For a tool whose sibling set contains another mailbox-status tool, that omission leaves real routing ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
mark_emailC
Update email flags such as marking as read/unread or starred/flagged.
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | The folder containing the message (default: 'INBOX'). | INBOX |
| is_read | No | If True, mark as read (Seen). If False, mark as unread. | |
| is_flagged | No | If True, star/flag the email. If False, unstar/unflag. | |
| message_id | Yes | The ID of the message to modify. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and falls short: it does not say the change is persisted server-side, whether it is reversible, whether unmentioned flags are left untouched, or whether any special permissions are required. 'Update' signals mutation but nothing about side effects or failure modes is disclosed.
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?
A single efficient sentence with the verb front-loaded and zero padding. The hedged 'such as' phrasing slightly weakens precision but costs nothing in length.
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?
For a simple flag-mutation tool with a fully documented schema and an output schema (so return values needn't be described), it is close to adequate. It still omits the important behavioral detail that null flag parameters mean 'no change' and says nothing about error conditions or idempotency.
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 baseline is 3. The description adds a small amount of value by mapping natural-language flag concepts (read/starred) onto the is_read/is_flagged parameters, but it does not explain the null default semantics (null = leave unchanged) or the folder default, which the schema already covers.
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?
States a specific verb and resource ('Update email flags') and enumerates the concrete flag operations (read/unread, starred/flagged), so an agent can distinguish it from siblings like move_email or delete_email. It does not explicitly name which sibling to use instead, but the resource is distinctive enough on its own.
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?
There is no statement of when to use this tool versus alternatives, and no prerequisites (e.g., that the message must already exist, or how it differs from read_email which presumably also marks as read). Usage is only implied by the operation name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
move_emailC
Move an email from one folder to another.
| Name | Required | Description | Default |
|---|---|---|---|
| message_id | Yes | The ID of the email to move. | |
| source_folder | No | Folder where the email is currently located (default: 'INBOX'). | INBOX |
| target_folder | No | Destination folder name (e.g. 'Trash', 'Archive', 'Drafts'). | Trash |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but only states the move operation. It omits key behavioral traits such as permissions needed, whether the move is reversible, and the significant default target of 'Trash' (which makes a bare call behave like a deletion).
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, front-loaded sentence with no wasted words. It is efficient, though extremely minimal.
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?
Although an output schema exists and the input schema is well documented, the tool is a mutation with no annotations. The description fails to mention the critical default behavior (moving to 'Trash') or side-effect context, leaving it incomplete for safe invocation.
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 message_id, source_folder, and target_folder including defaults. The description adds no parameter meaning beyond what the schema provides, so the baseline 3 applies.
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 states a specific verb ('Move') and resource ('an email') and the folder-to-folder action. It does not, however, explicitly differentiate from siblings like delete_email or mark_email, so it stops short of a 5.
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?
There is no when-to-use guidance, no exclusions, and no mention of alternatives such as delete_email or mark_email. The operation is only implied by the verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_emailC
Read the full content and details of a specific email message.
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | Mailbox folder containing the message (default: 'INBOX'). | INBOX |
| message_id | Yes | The ID of the message to read (from list_emails or search_emails). | |
| mark_as_read | No | Whether to automatically mark the email as read (Seen). Default is True. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cc | No | CC recipients |
| id | Yes | Message sequence ID in the mailbox |
| bcc | No | BCC recipients |
| uid | No | Unique IMAP UID |
| date | Yes | Date header |
| flags | No | IMAP flags (e.g. \Seen, \Flagged) |
| folder | Yes | Mailbox folder name |
| sender | Yes | Sender name and email (From header) |
| headers | No | Selected email headers |
| is_read | No | Whether email has been read |
| subject | Yes | Email subject |
| reply_to | No | Reply-To address |
| body_html | No | Raw HTML body if available |
| body_text | No | Plain text body or converted markdown body |
| is_flagged | No | Whether email is starred |
| message_id | No | Message-ID header |
| recipients | No | Recipients (To header) |
| attachments | No | List of attached files |
| in_reply_to | No | In-Reply-To header |
| sender_email | No | Clean sender email address |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It omits a meaningful side effect: mark_as_read defaults to true, meaning this 'read' operation mutates mailbox state (marks the message Seen) unless overridden. Permissions, error behavior on a bad message_id, and the side effect of reading are all undisclosed.
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?
A single focused sentence with no filler, and the purpose is front-loaded. It is efficient, though arguably too thin given the side-effect behavior it leaves unstated.
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?
An output schema exists, so return values need not be explained. However, with zero annotations and a default-true mutation (mark_as_read), the description should disclose the state-changing side effect and permission expectations to be fully adequate.
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 all three parameters (folder, message_id, mark_as_read) are already documented in the schema, including defaults. The description adds no parameter meaning beyond what the schema provides, so the baseline of 3 applies.
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 states a specific verb+resource ('Read the full content and details of a specific email message'), which is unambiguous. However, it does not distinguish itself from siblings such as list_emails or search_emails; the required message_id in the schema implies the distinction, not the description itself.
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?
There is no explicit guidance on when to use this tool versus search_emails or list_emails, nor any prerequisites or exclusions. The only hint of usage context ('from list_emails or search_emails') appears in the schema parameter description, not in the tool description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
reply_emailA
Reply to an existing email message.
Automatically handles 'Re:' subject prefix, In-Reply-To and References headers, recipient selection, and quoting the previous message.
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | The folder where the original email is located (default: 'INBOX'). | INBOX |
| body_html | No | Optional HTML body for the reply. | |
| body_text | Yes | Your reply message text. | |
| reply_all | No | If True, replies to all original recipients and CCs (excluding yourself). Default is False. | |
| message_id | Yes | The ID of the email to reply to. | |
| attachments | No | Optional local file paths to attach. |
Output Schema
| Name | Required | Description |
|---|---|---|
| message | Yes | Status description message |
| success | Yes | Whether sending succeeded |
| message_id | No | Generated Message-ID |
| recipients | No | List of recipient addresses |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose meaningful automatic behavior: 'Re:' prefix handling, In-Reply-To/References headers, recipient selection, and quoting the previous message. It stops short of stating that the reply is actually sent, any auth requirements, or irreversibility, which keeps it from a 5.
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?
Two sentences, zero waste, with the core action front-loaded and the automatic-handling details following. Every clause earns its place.
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?
Output schema exists so return values need not be explained. For a mutation tool with no annotations, the description covers the reply-construction behavior well, but omits whether the message is dispatched immediately and any permission requirements, leaving a small gap.
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 all six parameters (including folder default, reply_all, attachments) are already documented in the schema. The description's mention of 'recipient selection' loosely relates to reply_all but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.
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?
States a specific verb (reply) and resource (existing email message), which clearly differentiates it from send_email and forward_email in the sibling list. Missing an explicit sibling contrast, but the action is 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?
Usage is implied by 'reply to an existing email message' β an agent can infer this is for responding to a received message rather than composing or forwarding one. However, no explicit when-to-use guidance or comparison to send_email/forward_email is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_emailsC
Search for emails matching specific criteria.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return (default: 20). | |
| query | No | Free-text keyword search in subject and body. | |
| folder | No | Mailbox folder to search in (default: 'INBOX'). | INBOX |
| sender | No | Filter by sender name or email address (e.g. 'rektory@metu.edu.tr' or 'Ahmet'). | |
| subject | No | Filter by text contained in the subject line. | |
| recipient | No | Filter by recipient name or email. | |
| since_date | No | Search for emails received on or after this date (format: 'DD-Mon-YYYY', e.g. '01-Aug-2026'). | |
| before_date | No | Search for emails received before this date (format: 'DD-Mon-YYYY'). | |
| unread_only | No | If True, only match unread emails. | |
| flagged_only | No | If True, only match starred/flagged emails. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'Search' weakly implies a read-only, non-destructive operation, but the description discloses nothing about result ordering, pagination beyond the limit default, or whether unset filters broaden or narrow results.
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?
A single front-loaded sentence with zero padding. It is efficient, though the brevity is a consequence of under-specification rather than disciplined editing.
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?
An output schema exists so return values need not be explained, and the input schema is fully documented. However, for a 10-parameter search tool with no annotations, the description supplies no filter-combination semantics or routing guidance, leaving the agent to guess at invocation 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% β all 10 parameters carry their own descriptions, including formats and defaults. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.
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 gives a generic verb+resource ('Search for emails') but the qualifier 'matching specific criteria' is filler that adds no discriminating information. It does not distinguish this tool from the sibling list_emails, which an agent would need to know about to pick correctly.
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?
There is no when-to-use guidance, no mention of when search is preferable to list_emails, and no note about how filters combine (AND semantics) or what happens with all-null criteria. The agent must infer the entire usage model.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
send_emailB
Send a new email using your METU Webmail account.
| Name | Required | Description | Default |
|---|---|---|---|
| cc | No | Optional CC recipient(s). | |
| to | Yes | Recipient email address or list of email addresses (e.g. 'student@metu.edu.tr'). | |
| bcc | No | Optional BCC recipient(s). | |
| subject | Yes | Email subject line. | |
| reply_to | No | Optional custom Reply-To address. | |
| body_html | No | Optional formatted HTML body. | |
| body_text | Yes | Plain text body of the email. | |
| attachments | No | Optional list of local file paths to attach to the email. |
Output Schema
| Name | Required | Description |
|---|---|---|
| message | Yes | Status description message |
| success | Yes | Whether sending succeeded |
| message_id | No | Generated Message-ID |
| recipients | No | List of recipient addresses |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does not disclose that sending is irreversible, what account/permission is required, whether delivery failure is reported, or any rate limits β critical for an outbound-message tool.
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?
A single short sentence with no wasted words and the action front-loaded. It is efficient, though its brevity is partly a symptom of thin coverage rather than disciplined editing.
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?
An output schema exists, so return values need not be explained. However, for a mutating, irreversible tool with no annotations and rich sibling tooling (reply, forward), the description omits usage routing, side-effect disclosure, and auth expectations β too thin for this complexity.
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 every one of the 8 parameters (to, cc, bcc, subject, body_text, body_html, reply_to, attachments) is already documented in the schema. The description adds nothing beyond that, which is the correct baseline of 3.
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?
States a specific verb (send) and resource (new email) plus the account context (METU Webmail). The word 'new' implicitly separates it from reply_email and forward_email, but the description never names those siblings, so the distinction is left to inference.
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?
Usage is only implied by 'new email' β an agent can guess this is for composing rather than replying or forwarding, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many sibling mail tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
12 tool updates
v0.1.0- First observed
delete_email - First observed
forward_email - First observed
get_attachment - First observed
get_mailbox_status - First observed
list_emails - First observed
list_folders - First observed
mark_email - First observed
move_email - First observed
read_email - First observed
reply_email - First observed
search_emails - First observed
send_email
TDQS
Scored across 12 tools
Each tool maps to a distinct email action (move, delete, read, send, reply, forward, search, mark, attachment). The only mild overlap is between list_folders and get_mailbox_status, which both return folder names and message counts, though their descriptions are slightly differentiated.
All 12 tools follow a clean, consistent verb_noun snake_case pattern (list_emails, send_email, move_email, mark_email, etc.). No deviations in style or casing.
12 tools is a well-scoped set for an email client, covering the core read/compose/organize workflow without redundancy or filler.
Strong lifecycle coverage: list, search, read, send, reply, forward, move, delete, flag, and attachments. Minor gaps exist (e.g., no create_folder/rename folder or draft-save operation), but core email workflows are fully supported.
Maintenance
Related MCP Connectors
Email infrastructure for AI agents β send, receive, search, and reply to email over MCP.
Email inboxes and calendars for AI agents: send, receive, search, draft and schedule.
Email inboxes and calendars for AI agents: send, receive, search, draft and schedule.
- Lettio MCPOAutheu.lettio
Private, EU-hosted email for AI agents over JMAP: read, search, reply, organize, send.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to read, search, compose, and send emails by connecting to any IMAP/SMTP provider. It supports comprehensive mailbox management, including draft handling and message deletion, directly through natural language.10209 npm10MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with email accounts via IMAP and SMTP, supporting mailbox listing, email search, retrieval, sending, and management.MIT
- AlicenseBqualityDmaintenanceEnables AI assistants to send, read, and manage emails via SMTP and IMAP, with support for attachments, threads, and mailbox organization.166 npm1MIT
- FlicenseBqualityDmaintenanceEnables AI models to send, receive, search, and manage emails via SMTP/IMAP, including support for attachments, contacts, and advanced search.18-