Skip to main content
Glama
atesahmet0

metu-webmail-mcp

by atesahmet0

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 stdio mode and sse HTTP streaming mode.


Related MCP server: mcp-imap

πŸ› οΈ Installation & Setup

Prerequisites

  • Python 3.11+

  • uv (recommended) or pip

1. Clone & Install Dependencies

cd /Users/ates/Documents/projects/metu-webmail-mcp
uv sync

2. 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=587

Note: Both METU_USERNAME / METU_PASSWORD and SAIS_USERNAME / SAIS_PASSWORD are 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

get_mailbox_status

Returns overall account summary, email address, all folder metrics, and total unread count.

list_folders

Lists all mailbox folders with total and unread email counts.

list_emails

Lists recent emails from a folder (e.g. INBOX, Sent) with pagination (limit, offset) and preview snippets.

search_emails

Searches emails by text query, sender, recipient, subject, date ranges, unread only, or flagged only.

read_email

Reads full email content, decoded headers, markdown/html body, attachments list, and optionally marks as read.

get_attachment

Downloads/extracts attachment base64 content by filename or index.

send_email

Sends an email via METU SMTP with optional HTML body, CC, BCC, and file attachments.

reply_email

Replies to an existing email with automatic message threading and quoting.

forward_email

Forwards an existing email with optional comments to new recipients.

mark_email

Updates flags (read/unread, flagged/starred).

move_email

Moves an email from one folder to another.

delete_email

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 tools
delete_emailC

Delete an email message.

ParametersJSON Schema
NameRequiredDescriptionDefault
folderNoThe folder containing the email (default: 'INBOX').INBOX
permanentNoIf True, permanently expunges the message. If False (default), moves it to Trash.
message_idYesThe ID of the email to delete.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

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.

Conciseness3/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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).

ParametersJSON Schema
NameRequiredDescriptionDefault
toYesNew recipient email address or list of addresses.
folderNoThe folder where the original email is located (default: 'INBOX').INBOX
message_idYesThe ID of the email to forward.
attachmentsNoOptional additional file paths to attach.
additional_messageNoOptional note or comment to precede the forwarded message.

Output Schema

ParametersJSON Schema
NameRequiredDescription
messageYesStatus description message
successYesWhether sending succeeded
message_idNoGenerated Message-ID
recipientsNoList of recipient addresses

TDQS

C2.9/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
folderNoThe folder containing the email (default: 'INBOX').INBOX
message_idYesThe ID of the email message.
attachment_name_or_indexYesThe filename (e.g. 'syllabus.pdf') or part index number of the attachment.

Output Schema

ParametersJSON Schema
NameRequiredDescription
filenameYesName of the attached file
part_indexNoIndex of MIME part
size_bytesNoSize of attachment in bytes
content_typeYesMIME type of the attachment
content_base64NoBase64 encoded content (only if requested)

TDQS

B3.1/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
emailYesFull METU email address
foldersNoList of mailboxes
usernameYesMETU user account
total_unreadNoTotal unread messages across all folders

TDQS

A3.5/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of emails to retrieve (default: 20, max recommended: 50).
folderNoMailbox name to list emails from (e.g. 'INBOX', 'Sent', 'Drafts'). Default is 'INBOX'.INBOX
offsetNoOffset for pagination (default: 0).
unread_onlyNoIf True, only returns unread emails. Default is False.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior3/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
folderNoThe folder containing the message (default: 'INBOX').INBOX
is_readNoIf True, mark as read (Seen). If False, mark as unread.
is_flaggedNoIf True, star/flag the email. If False, unstar/unflag.
message_idYesThe ID of the message to modify.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
message_idYesThe ID of the email to move.
source_folderNoFolder where the email is currently located (default: 'INBOX').INBOX
target_folderNoDestination folder name (e.g. 'Trash', 'Archive', 'Drafts').Trash

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
folderNoMailbox folder containing the message (default: 'INBOX').INBOX
message_idYesThe ID of the message to read (from list_emails or search_emails).
mark_as_readNoWhether to automatically mark the email as read (Seen). Default is True.

Output Schema

ParametersJSON Schema
NameRequiredDescription
ccNoCC recipients
idYesMessage sequence ID in the mailbox
bccNoBCC recipients
uidNoUnique IMAP UID
dateYesDate header
flagsNoIMAP flags (e.g. \Seen, \Flagged)
folderYesMailbox folder name
senderYesSender name and email (From header)
headersNoSelected email headers
is_readNoWhether email has been read
subjectYesEmail subject
reply_toNoReply-To address
body_htmlNoRaw HTML body if available
body_textNoPlain text body or converted markdown body
is_flaggedNoWhether email is starred
message_idNoMessage-ID header
recipientsNoRecipients (To header)
attachmentsNoList of attached files
in_reply_toNoIn-Reply-To header
sender_emailNoClean sender email address

TDQS

C2.9/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
folderNoThe folder where the original email is located (default: 'INBOX').INBOX
body_htmlNoOptional HTML body for the reply.
body_textYesYour reply message text.
reply_allNoIf True, replies to all original recipients and CCs (excluding yourself). Default is False.
message_idYesThe ID of the email to reply to.
attachmentsNoOptional local file paths to attach.

Output Schema

ParametersJSON Schema
NameRequiredDescription
messageYesStatus description message
successYesWhether sending succeeded
message_idNoGenerated Message-ID
recipientsNoList of recipient addresses

TDQS

A3.8/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of results to return (default: 20).
queryNoFree-text keyword search in subject and body.
folderNoMailbox folder to search in (default: 'INBOX').INBOX
senderNoFilter by sender name or email address (e.g. 'rektory@metu.edu.tr' or 'Ahmet').
subjectNoFilter by text contained in the subject line.
recipientNoFilter by recipient name or email.
since_dateNoSearch for emails received on or after this date (format: 'DD-Mon-YYYY', e.g. '01-Aug-2026').
before_dateNoSearch for emails received before this date (format: 'DD-Mon-YYYY').
unread_onlyNoIf True, only match unread emails.
flagged_onlyNoIf True, only match starred/flagged emails.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.6/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose3/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
ccNoOptional CC recipient(s).
toYesRecipient email address or list of email addresses (e.g. 'student@metu.edu.tr').
bccNoOptional BCC recipient(s).
subjectYesEmail subject line.
reply_toNoOptional custom Reply-To address.
body_htmlNoOptional formatted HTML body.
body_textYesPlain text body of the email.
attachmentsNoOptional list of local file paths to attach to the email.

Output Schema

ParametersJSON Schema
NameRequiredDescription
messageYesStatus description message
successYesWhether sending succeeded
message_idNoGenerated Message-ID
recipientsNoList of recipient addresses

TDQS

B3.1/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines3/5

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.

  1. 12 tool updatesv0.1.0
    • First observeddelete_email
    • First observedforward_email
    • First observedget_attachment
    • First observedget_mailbox_status
    • First observedlist_emails
    • First observedlist_folders
    • First observedmark_email
    • First observedmove_email
    • First observedread_email
    • First observedreply_email
    • First observedsearch_emails
    • First observedsend_email

TDQS

B3.4/5.0

Scored across 12 tools

Disambiguation4/5

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.

Naming Consistency5/5

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.

Tool Count5/5

12 tools is a well-scoped set for an email client, covering the core read/compose/organize workflow without redundancy or filler.

Completeness4/5

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

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    D
    maintenance
    Enables 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.
    10
    209 npm
    10
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to interact with email accounts via IMAP and SMTP, supporting mailbox listing, email search, retrieval, sending, and management.
    MIT
  • A
    license
    B
    quality
    D
    maintenance
    Enables AI assistants to send, read, and manage emails via SMTP and IMAP, with support for attachments, threads, and mailbox organization.
    16
    6 npm
    1
    MIT
  • F
    license
    B
    quality
    D
    maintenance
    Enables AI models to send, receive, search, and manage emails via SMTP/IMAP, including support for attachments, contacts, and advanced search.
    18
    -