Skip to main content
Glama
Sign In
Apple Mail MCP

Apple Mail MCP

by cyberprive
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

save_all_attachments

Destructive

Save every attachment from an Apple Mail message into the configured attachments folder. Use optional subfolders and overwrite controls to organize files or avoid replacing existing ones.

Instructions

Save every attachment on a message, inside the attachments folder.

Same rules as save_attachment: writes only inside APPLE_MAIL_MCP_ATTACHMENTS_DIR, filenames cleaned, overwrite needs confirm.

Args: account, mailbox, id: As returned by search_messages. target_dir: Optional subfolder (relative, or absolute inside the folder). overwrite: If false (default), taken names get a " (2)", " (3)" suffix. True replaces existing files and requires confirm=true. confirm: Required with overwrite=true. Get the user's approval first.

Returns {saved: [{index, saved_path, name, original_name, size}], skipped: [{index, name, reason}]}. reason is typically "not_downloaded" — open the message in Mail.app to fetch it.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "account": "<account>",
      "mailbox": "<mailbox>",
      "id": "<id>"
    },
    "name": "save_all_attachments"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYes
accountYes
confirmNo
mailboxYes
overwriteNo
target_dirNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations flag the write/destructive profile, and the description adds real context beyond them: writes are confined to APPLE_MAIL_MCP_ATTACHMENTS_DIR, filenames are sanitized, non-overwrite collisions are auto-suffixed, and destructive replacement is gated behind confirm. It also explains the partial-failure case (skipped attachments with reason 'not_downloaded' and the fix of opening the message in Mail.app).

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?

Front-loads the one-line purpose, then groups rules, args, and return shape into clearly labeled blocks. No sentence is filler, and the confirm/overwrite interaction is stated once without repetition.

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?

Covers everything an agent needs for a destructive, multi-file write with no output schema: safety constraints, overwrite/confirm protocol, human-approval requirement, and an explicit return shape including the skipped list and its most likely reason.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden, and it defines all six parameters: account/mailbox/id sourced from search_messages, target_dir as relative or absolute inside the attachment root, overwrite default false with its collision behavior, and confirm's dependency on overwrite=true.

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?

Names a specific verb and resource ('Save every attachment on a message') and states the destination ('inside the attachments folder'), which cleanly separates it from the single-attachment sibling save_attachment.

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

Usage Guidelines4/5

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

Gives concrete operational guidance: overwrite=false produces ' (2)' suffixes, overwrite=true replaces files and requires confirm=true with prior user approval, and points to save_attachment as the source of shared rules. It stops short of an explicit 'use this instead of save_attachment when the message has multiple attachments', so the bulk-vs-single choice is inferred rather than stated.

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

Deploy Server

Other Tools