apple-mail-mcp

Overview Schema Source Related Servers Discussions Admin

search-messages

Find email messages by sender, subject, body, date, read, or flag filters, returning IDs for follow-up actions like reading or deleting.

Instructions

Use when: finding messages by query/sender/subject/date/read/flag filters and you need their ids for follow-up operations. Returns: matching messages with id, date, subject, sender, and read state (plus partial-coverage diagnostics when some mailboxes were skipped). Do not use when: you want a plain mailbox listing without filters (use list-messages), already have an id and want the body (use get-message), or want a whole conversation (use get-thread). Prefer this first to obtain the message ids that get-message/mark-as-read/delete-message/move-message and the batch tools require.

Input Schema

TableJSON Schema

Name	Required	Description
`body`	No	Text to search for in the message body (server-side IMAP BODY search). Requires the IMAP backend for the account searched; AppleScript-only accounts cannot search bodies and are reported as not searched.
`from`	No	Filter by sender (substring match against the full sender string, i.e. display name + address — not an exact address match)
`limit`	No	Maximum number of results (default: 50, max: 500)
`query`	No	Text to search for in subject or sender
`dateTo`	No	End date filter (e.g., 'March 1, 2026')
`isRead`	No	Filter by read status
`account`	No	Account to search in (omit to search all accounts)
`mailbox`	No	Mailbox to search in (e.g., 'INBOX'). Omit to search all mailboxes.
`subject`	No	Filter by subject line (substring match)
`dateFrom`	No	Start date filter (e.g., 'January 1, 2026')
`isFlagged`	No	Filter by flagged status

Output Schema

TableJSON Schema

Name	Required	Description	Default
`count`	No
`partial`	No
`messages`	No
`failedMailboxes`	No
`timedOutAccounts`	No
`failedMailboxReasons`	No
`notSearchedMailboxes`	No
`skippedLargeMailboxes`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv2.19.14Sep 23, 2026
- addedOutput schema / properties / failedMailboxReasons
```
Added value: +{
+  "additionalProperties": {
+    "type": "string"
+  },
+  "type": "object"
+}
```

Changed2 schema fields changedv2.19.12Sep 22, 2026

addedInput schema / properties / body

Added value: +{
+  "description": "Text to search for in the message body (server-side IMAP BODY search). Requires the IMAP backend for the account searched; AppleScript-only accounts cannot search bodies and are reported as not searched.",
+  "type": "string"
+}

changedInput schema / properties / query / description

Previous value: -"Text to search for in subject, sender, or content"New value: +"Text to search for in subject or sender"

Changed1 schema field changedv2.17.2Aug 28, 2026
- addedOutput schema / properties / failedMailboxes
```
Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
```

Changed2 schema fields changedv2.10.24Aug 14, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Changed1 schema field changedv2.10.8Aug 7, 2026
- changedOutput schema / additionalProperties
```
Previous value: -falseNew value: +true
```
Addedv2.9.0Jul 29, 2026
Removedv2.8.10Jul 18, 2026
Changed4 schema fields changedv2.8.2Jul 4, 2026
- changedInput schema / properties / limit / description
```
Previous value: -"Maximum number of results (default: 50)"New value: +"Maximum number of results (default: 50, max: 500)"
```
- addedInput schema / properties / limit / maximum
```
Added value: +500
```
- addedInput schema / properties / limit / minimum
```
Added value: +1
```
- changedInput schema / properties / limit / type
```
Previous value: -"number"New value: +"integer"
```
First observedv2.6.1Jun 29, 2026

TDQS

A4.5/5.0

Behavior4/5

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

With no annotations provided, the description carries the full behavioral disclosure burden. It discloses return fields and, notably, partial-coverage diagnostics when some mailboxes are skipped—an important non-obvious behavior. It does not explicitly state that searching has no side effects, but the read-only nature is strongly implied by the operation type.

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?

The description is compact, well-organized into use conditions, return behavior, exclusions, and downstream guidance. Every sentence provides distinct value and the most important routing information is front-loaded.

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 11 optional parameters, a rich sibling list, and the presence of an output schema, the description covers what the tool is for, when to use it instead of alternatives, what it returns, and how it fits into follow-up workflows. Nothing essential for correct selection and invocation is missing.

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 documentation covers 100% of the 11 parameters, so the baseline is 3. The description groups filters at a category level (query/sender/subject/date/read/flag) but does not add deep meaning beyond the schema; the schema itself explains each parameter adequately.

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 names a specific operation—finding messages by query/sender/subject/date/read/flag filters—and states the key output: matching message IDs for follow-up operations. It also explicitly contrasts itself with list-messages, get-message, and get-thread, so an agent can distinguish it from nearby siblings.

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?

Uses explicit 'Use when' and 'Do not use when' guidance with named alternatives for each exclusion case. It also tells the agent to prefer this tool first when message IDs are needed for downstream tools, which is actionable routing guidance.

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

Deploy Server