Local MCP

List Emails

list_emails

Read-only

Use this when the user wants to see or triage their inbox on this Mac (Apple Mail — any account added to Mail.app: iCloud, Gmail, IMAP, Exchange). Lists email headers (subject, sender, date, unread); call read_email(message_id) for the full body. For a Microsoft 365 mailbox NOT added to Mail.app, use m365_list_emails.

IMPORTANT: on machines with 2+ accounts, call with account= (from list_email_accounts). Without it, and when the fast index can't answer, list_emails returns the account list instead of scanning all of them — scanning every account in one call has no time limit and can block Mail for other requests too (#2268). Exactly 1 account is unaffected.

Supports pagination: use offset to page through results (e.g. offset=20 for page 2 with limit=20). The limit parameter is capped at 50 per call (default 20); to read more, page with offset rather than requesting a larger limit.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	How many messages to return, 0-50 (0 returns none). Defaults to 20.	20
`offset`	No	How many messages to skip before returning, for paging through a folder. Defaults to 0.	0
`account`	No	Mail.app account name (from list_email_accounts). On a Mac with 2+ accounts, passing it is much faster than letting the walk cover all of them.
`mailbox`	No	Folder to list, by name (see list_email_folders). Defaults to the Inbox.
`unread_only`	No	Return only unread messages. Defaults to false.	false

Output Schema

TableJSON Schema

Name	Required	Description	Default
`count`	No
`offset`	No
`messages`	No
`next_actions`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedSep 30, 2026

addedInput schema / properties / account / description

Added value: +"Mail.app account name (from list_email_accounts). On a Mac with 2+ accounts, passing it is much faster than letting the walk cover all of them."

addedInput schema / properties / limit / description

Added value: +"How many messages to return, 0-50 (0 returns none). Defaults to 20."

changedInput schema / properties / limit / minimum
```
Previous value: -1New value: +0
```

addedInput schema / properties / mailbox / description

Added value: +"Folder to list, by name (see list_email_folders). Defaults to the Inbox."

addedInput schema / properties / offset / description

Added value: +"How many messages to skip before returning, for paging through a folder. Defaults to 0."

addedInput schema / properties / unread_only / description

Added value: +"Return only unread messages. Defaults to false."

Changed6 schema fields changedSep 29, 2026

removedInput schema / properties / account / description

Removed value: -"Mail.app account name (from list_email_accounts). On a Mac with 2+ accounts, passing it is much faster than letting the walk cover all of them."

removedInput schema / properties / limit / description

Removed value: -"How many messages to return, 0-50 (0 returns none). Defaults to 20."

changedInput schema / properties / limit / minimum
```
Previous value: -0New value: +1
```

removedInput schema / properties / mailbox / description

Removed value: -"Folder to list, by name (see list_email_folders). Defaults to the Inbox."

removedInput schema / properties / offset / description

Removed value: -"How many messages to skip before returning, for paging through a folder. Defaults to 0."

removedInput schema / properties / unread_only / description

Removed value: -"Return only unread messages. Defaults to false."

Changed2 schema fields changedSep 26, 2026

changedInput schema / properties / limit / description

Previous value: -"How many messages to return, 1-50. Defaults to 20."New value: +"How many messages to return, 0-50 (0 returns none). Defaults to 20."

changedInput schema / properties / limit / minimum
```
Previous value: -1New value: +0
```

Changed5 schema fields changedSep 20, 2026

addedInput schema / properties / account / description

Added value: +"Mail.app account name (from list_email_accounts). On a Mac with 2+ accounts, passing it is much faster than letting the walk cover all of them."

addedInput schema / properties / limit / description

Added value: +"How many messages to return, 1-50. Defaults to 20."

addedInput schema / properties / mailbox / description

Added value: +"Folder to list, by name (see list_email_folders). Defaults to the Inbox."

addedInput schema / properties / offset / description

Added value: +"How many messages to skip before returning, for paging through a folder. Defaults to 0."

addedInput schema / properties / unread_only / description

Added value: +"Return only unread messages. Defaults to false."

First observedJun 30, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the readOnlyHint annotation, the description discloses important behavior: on multi-account machines without an account parameter, it may return the account list instead of scanning all accounts, and scanning all accounts can block Mail for other requests. This is valuable operational context the annotations do not provide.

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 dense but every sentence earns its place: use case, sibling routing, multi-account warning, and pagination behavior. It is front-loaded with the primary purpose and uses clear paragraph breaks for distinct concerns.

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 output schema exists and the input schema covers all parameters, the description provides the missing contextual pieces: when to use it, how it differs from siblings, the account-selection caveat, and pagination limits. Nothing an agent needs to call this tool correctly 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 baseline is 3. The description adds extra meaning by explaining the account parameter's source (list_email_accounts), the multi-account performance implications, and the pagination pattern with offset and limit. It mostly reinforces schema details but does add practical usage guidance.

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 states a specific verb and resource: 'Lists email headers (subject, sender, date, unread)' for Apple Mail accounts on this Mac. It also differentiates itself from read_email and m365_list_emails, making the tool's scope unmistakable.

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 says when to use the tool ('when the user wants to see or triage their inbox on this Mac') and names the alternative for Microsoft 365 mailboxes not in Mail.app. It also gives concrete guidance for multi-account machines, telling the agent to pass account=<name> from list_email_accounts.

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

All Local MCP tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.