Mail.app

NPM · @P-L-TA/MAIL-MCP · SCANNED AUG 3

Search, read, send, and manage email via macOS Mail.app across all configured accounts.

Available components

+52 this week 76 76 Trust /100

Trust breakdown (6 categories)

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. How we score →

Supply Chain Security86

No malware found by supply-chain analysis.Pass
Only part of the dependency tree could be resolved (94 of 98), so this covers what we could see, not the whole tree.Partial
No install/post-install scripts declared.Pass
Only part of the dependency tree could be resolved (94 of 98), so this covers what we could see, not the whole tree. View diagnostics → Partial

Provenance & Transparency97

Source repository is publicly reachable at the declared URL. View diagnostics → Pass
Cryptographically verified build provenance (signed, bound to p-l-ta/mail-mcp). View diagnostics → Pass
Clear OSI-approved license (MIT).Pass
Actively maintained (last published 23 days ago).Pass
Disclosure check failed: no security disclosure policy was found in the source repository. See how to fix → Fail

Schema Quality & AI Usability81

AI-judged instruction clarity (excellent).Pass
Tool/resource definitions use about 2285 tokens (~95/item across 24 items; 24 tools + 0 resources), lean.Pass
Usage-examples check failed: none of the tools include examples. See how to fix → Fail

Stability & Change Management0

Stability not yet verified: not enough scan history yet (needs a 30-day window).Unverified

Tool Coverage94

100% of tools have a non-trivial description (not blank, and not just the tool's name).Pass
83% of tool parameters carry a description.Partial

Capabilities100

Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.Pass

Unverified: 1 category

A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

Install

Add this component to your MCP client. Where a client-specific snippet is available, pick your client below and copy it straight into your config; otherwise use the connection detail shown.

npm · @p-l-ta/mail-mcp

Claude Codex opencode OpenClaw Hermes Other

# add to Claude Code

claude mcp add p-l-ta-mail-mcp -- npx -y @p-l-ta/mail-mcp

# add to Codex CLI

codex mcp add p-l-ta-mail-mcp -- npx -y @p-l-ta/mail-mcp

// opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "p-l-ta-mail-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@p-l-ta/mail-mcp"
      ],
      "enabled": true
    }
  }
}

# add to OpenClaw

openclaw mcp add p-l-ta-mail-mcp --command npx --arg -y --arg @p-l-ta/mail-mcp

# ~/.hermes/config.yaml

mcp_servers:
  p-l-ta-mail-mcp:
    command: "npx"
    args: ["-y", "@p-l-ta/mail-mcp"]

// mcp.json

{
  "mcpServers": {
    "p-l-ta-mail-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@p-l-ta/mail-mcp"
      ]
    }
  }
}

Changelog

Every change we have recorded for this component, newest first. Security-relevant changes are always shown. ▲ marks a change for the better, ▼ a change for the worse; unmarked changes are neutral.

2 Aug 26 +56
- Install scripts: unverified → pass ▲ security
- Provenance: unverified → pass ▲ security
- Known CVEs: unverified → partial ▲ security
- Malware scan: unverified → pass ▲ security
- Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window). security
- The attested source repository moved: p-l-ta/mail-mcp security
- Schema quality: unverified → excellent ▲ functional
- License: unverified → pass ▲ functional
- Dependency health: unverified → partial ▲ functional
- Maintenance: unverified → pass ▲ functional
- MCP protocol: unverified → pass ▲ functional
- Licence: MIT functional
31 Jul 26 −8
- We updated how we score, so this day's move reflects our rubric, not a change to the server See what changed → functional
30 Jul 26 −18
- Malware scan: pass → unverified ▼ security
28 Jul 26 +22
- Tool coverage: unverified → 100 ▲ functional
- First check of Schema quality: unverified functional
- First check of Schema quality: fail functional
- First check of Tool coverage: 83 functional
- First check of Schema quality: pass functional
27 Jul 26 24

First indexed and scored.

Show 3 earlier entries Hide earlier entries

Diagnostics

Diagnostic detail from the automated scan of this channel: what the scanner observed at each step, so you can see exactly where a check passed or failed. It is informational only and never changes the trust score.

Captured 3 Aug 2026 · Analysed npm/@p-l-ta/[email protected]

Provenance verified

Ecosystem: npm · Outcome: verified

Reason: verified

Source repo:: p-l-ta/mail-mcp
Certificate issuer:: https://token.actions.githubusercontent.com
Certificate SAN:: https://github.com/p-l-ta/mail-mcp/.github/workflows/release.yml@refs/tags/v1.3.5
Rekor log index:: 2138143320
Predicate type:: https://slsa.dev/provenance/v1
Subject digest:: sha512:65ace792600578f344e778f9128c26d5d2615c84b4d773deda74c3b969ef86ab6eaad5c373b7749fc37befb3baf5d97a76b560c17333dcf3de869d9a1
Discovery method:: attestation_endpoint

Dependencies 94 packages

94 packages in the resolved dependency tree · 94 deprecated · 29 stale.

The dependency tree was only partially resolved, so these counts may be incomplete.

MCP tools — 24 exposed · ~2,285 tokens

The tools this component advertises to a client, with an estimated token cost for each. Expand a tool to see its parameters and schema. The per-tool counts are indicative and are not scored directly; the schema's total context footprint is one signal in Schema Quality & AI Usability.

Tool Tokens

bulk_apply ~169

Apply one action (mark_read, mark_unread, flag, unflag, trash, or move) to a list of messages by RFC message-id, in a single batched call — far faster than calling set_message_flags/trash_email/move_email once per message.

Input Output Examples

Name	Type	Req	Description
destination_account	string	—	Account name to disambiguate if multiple accounts share the destination mailbox name
destination_mailbox	string	—	Required when op is 'move'. Exact mailbox name from list_accounts_and_mailboxes.
message_ids	array	yes	RFC message-ids (with or without angle brackets) from search/list results
op	string	yes	Action to apply to every message: mark_read, mark_unread, flag, unflag, trash, or move (move requires destination_mailbox)

No output schema declared.

No examples provided.

bulk_flag ~153

Flag or unflag multiple messages in one call — by mailbox, sender substring, or both. Queries the Envelope Index for matching IDs then updates in a single batched AppleScript call.

Input Output Examples

Name	Type	Req	Description
account	string	—	Restrict to this account (substring match against mailbox URL host).
flagged	boolean	yes	Target flagged state to apply to every matching message.
from	string	—	Substring to match against the sender address or display name. At least one of mailbox or from is required.
limit	integer	—	Maximum number of messages to update in one call.
mailbox	string	—	Restrict to this exact mailbox name (matched against mailbox URL). At least one of mailbox or from is required.

No output schema declared.

No examples provided.

bulk_mark_read ~99

Mark multiple messages as read in one call — by mailbox, sender substring, or both. Far faster than calling set_message_flags per message.

Input Output Examples

Name	Type	Req	Description
account	string	—	Restrict to this account name.
from	string	—	Substring to match against the sender field. At least one of mailbox or from is required.
mailbox	string	—	Restrict to this exact mailbox name. At least one of mailbox or from is required.

No output schema declared.

No examples provided.

bulk_move ~194

Move multiple messages to a destination mailbox in one call — by mailbox, sender substring, or both. Queries the Envelope Index for matching IDs then moves in a single batched AppleScript call.

Input Output Examples

Name	Type	Req	Description
account	string	—	Restrict source to this account (substring match against mailbox URL host).
destination_account	string	—	Account name to disambiguate if multiple accounts share the destination mailbox name
destination_mailbox	string	yes	Exact mailbox name from list_accounts_and_mailboxes (slash-pathed for nested, e.g. 'Folders/Amtrak')
from	string	—	Substring to match against the sender address or display name. At least one of mailbox or from is required.
limit	integer	—	Maximum number of messages to move in one call.
mailbox	string	—	Restrict source to this mailbox name (matched against mailbox URL). At least one of mailbox or from is required.

No output schema declared.

No examples provided.

bulk_trash ~138

Move multiple messages to trash in one call — by mailbox, sender substring, or both. Queries the Envelope Index for matching IDs then trashes in a single batched AppleScript call.

Input Output Examples

Name	Type	Req	Description
account	string	—	Restrict to this account (substring match against mailbox URL host).
from	string	—	Substring to match against the sender address or display name. At least one of mailbox or from is required.
limit	integer	—	Maximum number of messages to trash in one call.
mailbox	string	—	Restrict to this exact mailbox name (matched against mailbox URL). At least one of mailbox or from is required.

No output schema declared.

No examples provided.

check_compatibility ~52

Probe each mail-mcp dependency (Envelope Index schema, SyncedRules.plist, AppleScript, MailData directory) and report pass/fail. Run this after a macOS update to verify nothing broke.

Input Output Examples

Input schema present but exposes no named parameters.

No output schema declared.

No examples provided.

create_mailbox ~65

Create a new mailbox (folder) in a Mail.app account.

Input Output Examples

Name	Type	Req	Description
account	string	—	Account name to create it in. Required when multiple accounts are configured; use name from list_accounts_and_mailboxes.
name	string	yes	Name for the new mailbox/folder

No output schema declared.

No examples provided.

create_rule ~104

Create a new Mail.app rule. A timestamped backup of SyncedRules.plist is made before writing. Mail.app may need to be restarted for the rule to take effect.

Input Output Examples

Name	Type	Req	Description
actions	object	yes	At least one action should be set.
conditions	array	yes	One or more match conditions.
match_all	boolean	—	true = ALL conditions must match (AND); false = ANY (OR).
name	string	yes	Display name for the rule.

No output schema declared.

No examples provided.

delete_rule ~75

Permanently delete a Mail.app rule by its RuleId. A timestamped backup of SyncedRules.plist is made before writing so the deletion can be undone. Mail.app may need to be restarted for the change to take effect.

Input Output Examples

Name	Type	Req	Description
rule_id	string	yes	The RuleId of the rule to delete (from list_rules).

No output schema declared.

No examples provided.

empty_mailbox ~108

Delete every message in a mailbox at once — moves to Deleted Messages, or permanently removes if the mailbox is already Deleted Messages/Trash. Use for Junk, Trash, or bulk-cleanup folders.

Input Output Examples

Name	Type	Req	Description
account	string	—	Account name to disambiguate when the same mailbox name exists in multiple accounts
mailbox_name	string	yes	Exact mailbox name to empty (e.g. 'Junk', 'Deleted Messages', 'Other Inbox'). Use list_accounts_and_mailboxes for exact names.

No output schema declared.

No examples provided.

get_unsubscribe_link ~55

Extract unsubscribe URLs from a message — checks the List-Unsubscribe header first (reliable), then scans the plain-text body as a fallback.

Input Output Examples

Name	Type	Req	Description
message_id	string	yes	RFC message-id (with or without angle brackets)

No output schema declared.

No examples provided.

list_accounts_and_mailboxes ~25

List all configured Mail.app accounts and their mailboxes with unread counts.

Input Output Examples

Input schema present but exposes no named parameters.

No output schema declared.

No examples provided.

list_recent ~55

List recent messages in a mailbox of a specific account.

Input Output Examples

Name	Type	Req	Description
account	string	yes	Account name as shown in Mail.app
limit	integer	—	—
mailbox	string	—	—
unread_only	boolean	—	—

No output schema declared.

No examples provided.

list_rules ~28

List all Mail.app rules with their conditions and actions. Reads directly from SyncedRules.plist.

Input Output Examples

Input schema present but exposes no named parameters.

No output schema declared.

No examples provided.

list_senders ~179

Return a grouped count of senders across mailboxes — who sends how many messages, how many are unread, and when the last arrived. By default excludes Deleted Messages, Junk, Sent, and Drafts so counts reflect live mail only. Ideal for identifying bulk senders and noise.

Input Output Examples

Name	Type	Req	Description
account	string	—	Account host/name substring to restrict to
include_system_mailboxes	boolean	—	When true, include Deleted Messages, Junk, Sent Messages, and Drafts in unscoped queries. Has no effect when mailbox is specified.
limit	integer	—	Max senders to return, ordered by message count desc
mailbox	string	—	Mailbox name or URL substring to restrict to (e.g. 'INBOX', 'Amtrak'). When omitted, covers all non-system mailboxes (see include_system_mailboxes).

No output schema declared.

No examples provided.

move_email ~103

Move a message to a different mailbox by RFC message-id. Use list_accounts_and_mailboxes to get exact mailbox names.

Input Output Examples

Name	Type	Req	Description
destination_account	string	—	Account name to disambiguate if multiple accounts share the mailbox name
destination_mailbox	string	yes	Exact mailbox name from list_accounts_and_mailboxes (slash-pathed for nested, e.g. 'Folders/Amtrak')
message_id	string	yes	RFC message-id (with or without angle brackets)

No output schema declared.

No examples provided.

read_email ~67

Read full body of a message by its RFC message-id. Uses Mail.app via AppleScript so it works for IMAP/iCloud/Exchange messages without filesystem access.

Input Output Examples

Name	Type	Req	Description
message_id	string	yes	RFC message-id (with or without angle brackets) from search_emails / list_recent results

No output schema declared.

No examples provided.

reply_to_email ~50

Reply to an existing message identified by RFC message-id.

Input Output Examples

Name	Type	Req	Description
body	string	yes	—
message_id	string	yes	RFC message-id from search/list results
reply_all	boolean	—	—

No output schema declared.

No examples provided.

search_emails ~183

Search Mail.app messages via the Envelope Index database. Returns rich metadata including RFC message-id (usable with read_email, reply_to_email, set_message_flags).

Input Output Examples

Name	Type	Req	Description
account	string	—	Substring match against the full mailbox URL (host and path). Use the account hostname to target an account (e.g. 'icloud'), or a mailbox path segment to target a specific folder (e.g. 'INBOX', 'Amtr…
from	string	—	Substring match on sender address or display name
include_deleted	boolean	—	—
limit	integer	—	—
query	string	—	Free-text search across subject, sender, and body summary. Omit to list-only by other filters.
since	string	—	ISO date — only messages on or after this date
subject	string	—	Substring match on subject

No output schema declared.

No examples provided.

send_email ~75

Send a new email via Mail.app from an existing account.

Input Output Examples

Name	Type	Req	Description
body	string	yes	—
cc	string	—	CC recipient email address
from_account	string	—	Account name to send from (matches Mail.app account name)
subject	string	yes	—
to	string	yes	Primary recipient email address

No output schema declared.

No examples provided.

set_message_flags ~46

Set read and/or flagged status on a message identified by RFC message-id.

Input Output Examples

Name	Type	Req	Description
flagged	boolean	—	—
message_id	string	yes	—
read	boolean	—	—

No output schema declared.

No examples provided.

submit_feedback ~87

Open a pre-filled GitHub issue for mail-mcp (p-l-ta/mail-mcp) in the default browser. Automatically includes macOS version and mail-mcp version in the issue body.

Input Output Examples

Name	Type	Req	Description
description	string	yes	Description of the problem or feedback. Include steps to reproduce if reporting a bug.
title	string	—	Short issue title (optional — a default will be generated).

No output schema declared.

No examples provided.

trash_email ~44

Move a message to Deleted Messages (trash) by RFC message-id. Does not permanently delete.

Input Output Examples

Name	Type	Req	Description
message_id	string	yes	RFC message-id (with or without angle brackets)

No output schema declared.

No examples provided.

update_rule ~131

Update an existing Mail.app rule by its RuleId (use list_rules to find IDs). A timestamped backup is made before writing. Mail.app may need to be restarted for changes to take effect.

Input Output Examples

Name	Type	Req	Description
actions	object	—	Partial actions update — only supplied fields are changed.
conditions	array	—	Replace the full conditions list. Omit to leave unchanged.
match_all	boolean	—	true = ALL (AND); false = ANY (OR).
name	string	—	New display name.
rule_id	string	yes	The RuleId of the rule to update (from list_rules).

No output schema declared.

No examples provided.

On this page

Handy links

Scoring key

80+ high trust
60–79 medium
below 60 low

How we score

Score history · last 30 days

27 Jul 3 Aug