Skip to main content
Glama
apple-mail-readonly-mcp

apple-mail-readonly-mcp

by hzcsj

Apple Mail Read-Only MCP

A local MCP server for searching and reading downloaded Apple Mail data without changing mail state. It can run with any compatible MCP client and includes optional Codex plugin packaging.

Features

  • List Apple Mail accounts and mailboxes

  • Search local metadata (subject, sender, date) without reading bodies

  • Read selected downloaded message bodies with strict size limits

  • Read bounded local threads/conversations

  • List attachment metadata only (no export)

  • Full Disk Access diagnostics

Related MCP server: apple-mail-mcp

Requirements

  • macOS

  • Python 3.11+

  • Apple Mail configured locally

  • Full Disk Access may be required for the launcher process

Quick Start

# Run the MCP server
bash scripts/run_mcp.sh

# Run tests
python3 -m unittest discover -s tests -v

# Static security check
python3 scripts/doctor.py --static

# Live smoke test (opt-in)
APPLE_MAIL_READONLY_RUN_LIVE=1 python3 scripts/smoke_test.py

MCP Tools (v0.1)

Tool

Purpose

mail_health_check

Verify server, platform, Mail store discovery

mail_permissions_check

Diagnose Full Disk Access

mail_list_accounts

List account coverage

mail_list_mailboxes

List mailboxes/folders

mail_search_messages

Search local metadata (no body read)

mail_read_message

Read a selected downloaded message

mail_read_thread

Read a bounded local thread

mail_list_attachments

List attachment metadata

Non-Goals

This server will never:

  • Send email

  • Create drafts

  • Reply/forward

  • Move, delete, archive, mark read/unread, flag

  • Export/open/download attachments

  • Run arbitrary scripts

  • Update itself

Installation

Run scripts/run_mcp.sh from any MCP client that supports stdio servers. See docs/codex-install.md for Codex plugin installation instructions.

Privacy and Security

Mail content stays on the local machine. The server opens the Apple Mail index in SQLite read-only mode, registers no write-capable tools, makes no mail-provider API calls, and never exports attachment contents. See docs/security-model.md for the complete guarantees and limitations.

License

MIT

Available Tools

8 tools
mail_health_checkB

Verify server, platform, Mail store discovery, and read-only database access.

Inputs: include_paths.

mail_list_accountsC

List account UUID coverage from the local Envelope Index.

Inputs: limit, include_email_addresses.

mail_list_attachmentsA

List attachment metadata for one downloaded message. Does not export content.

Inputs: local_id, message_id.

mail_list_mailboxesB

List mailboxes/folders with optional filters.

Inputs: role, limit, query, account_uuid, +1 more.

mail_permissions_checkC

Diagnose Full Disk Access and optional settings guidance.

Inputs: open_full_disk_access.

mail_read_messageB

Read a selected downloaded message by local id or message id.

Inputs: local_id, message_id, body_format, include_body, +3 more.

mail_read_threadC

Read a bounded local thread/conversation.

Inputs: limit, local_id, message_id, body_format, +3 more.

mail_search_messagesA

Search local metadata newest-first. Does not read message bodies.

Inputs: limit, query, sender, date_to, +14 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct function: health check, account listing, attachment metadata, mailbox listing, permissions, message reading, thread reading, and search. No overlap in purpose.

    Naming Consistency5/5

    All tools follow the 'mail_verb_noun' pattern with snake_case, e.g., mail_list_accounts, mail_read_message, providing strong predictability.

    Tool Count5/5

    8 tools cover the core read-only operations on Apple Mail without being excessive or insufficient for the domain.

    Completeness4/5

    Covers health, permissions, account/mailbox listing, message/thread reading, search, and attachment metadata. Missing bulk message listing and attachment content export, but reasonable for read-only scope.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Local MCP server for multi-account IMAP/SMTP email (iCloud + Gmail via app-specific passwords). Never marks mail read. Cross-folder search, idempotent sends, TLS verified.
      8
      35 PyPI
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A read-only MCP server for Apple Mail on macOS that enables searching and reading emails directly from the local SQLite database, with fast SQL-level filtering and pagination.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that drives macOS Mail: read, search, send, organise.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Apple Mail that reads from Mail's SQLite store for fast queries and writes through Mail.app via AppleScript, enabling mailbox management, search, drafts, and message updates without sending mail.
      MIT