Selfhost-Remote-Mail-MCP

emails

Read-only

List messages in a mail folder with ID, date, sender, recipients, subject, and flags. Filter by sender, date, read state, attachments, or keywords without marking anything read.

Instructions

List the emails in one folder (default: the first mailbox's Inbox), one line each with ID, date, From, To, Subject and flags, plus the total and page count. No bodies: read an email with thread; to look across folders or by keywords use search. Changes nothing (nothing is marked as read). page_size is at most 200.

filter is Gmail-style and can combine: from:, to:, cc:, subject:, before:yyyy/MM/dd, after:yyyy/MM/dd, newer_than:7d (d/w/m/y), older_than:, is:unread, is:read, is:starred/is:pinned, is:answered, has:attachment, filename:, plain words (full-text), and -term to exclude.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`page`	No	Which page of results, starting at 1.
`order`	No	descending (newest first) or ascending (oldest first).	descending
`filter`	No	Gmail-style filter, can combine: from:, to:, cc:, subject:, before:yyyy/MM/dd, after:yyyy/MM/dd, newer_than:7d (d/w/m/y), older_than:, is:unread, is:read, is:starred, is:answered, has:attachment, filename:<name>, plain words, and -term to exclude.
`folder`	No	The folder, like 'INBOX' or 'Archive'. Another mailbox: 'you@example.com:INBOX', or just its address for its Inbox. Empty means the first mailbox's Inbox.
`page_size`	No	How many emails per page.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedOct 21, 2026

addedInput schema / properties / filter / description

Added value: +"Gmail-style filter, can combine: from:, to:, cc:, subject:, before:yyyy/MM/dd, after:yyyy/MM/dd, newer_than:7d (d/w/m/y), older_than:, is:unread, is:read, is:starred, is:answered, has:attachment, filename:<name>, plain words, and -term to exclude."

addedInput schema / properties / folder / description

Added value: +"The folder, like 'INBOX' or 'Archive'. Another mailbox: 'you@example.com:INBOX', or just its address for its Inbox. Empty means the first mailbox's Inbox."

addedInput schema / properties / order / description

Added value: +"descending (newest first) or ascending (oldest first)."

addedInput schema / properties / page / description

Added value: +"Which page of results, starting at 1."

addedInput schema / properties / page_size / description
```
Added value: +"How many emails per page."
```

First observedv0.19.1Oct 20, 2026

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare `readOnlyHint=true`, and the description reinforces that nothing changes and nothing is marked as read. It also adds useful behavior not in annotations: no bodies are returned and `page_size` is capped at 200.

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 front-loaded with the core purpose and alternatives, then proceeds to behavior and parameter limits. It is dense and useful, though the long `filter` syntax list duplicates schema content and could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the read-only annotations and an output schema, the description supplies everything needed: scope, default folder, output shape, alternatives, side-effect behavior, and page-size limit. No critical invocation detail is missing.

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?

Schema coverage is 100%, so the schema already documents all parameters. The description adds some meaning beyond the schema, especially the `page_size` maximum of 200 and the default folder behavior, though much of the `filter` syntax repeats the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource: list emails in one folder, with default scope and output fields. It clearly distinguishes this from siblings by naming `search` for cross-folder/keyword lookup and `thread` for reading bodies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use this tool and when to use alternatives: use this for one folder's email list, use `thread` to read an email, and use `search` to look across folders or by keywords. These are concrete routing instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server