# 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

## Requirements

- macOS
- Python 3.11+
- Apple Mail configured locally
- Full Disk Access may be required for the launcher process

## Quick Start

```bash
# 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`](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`](docs/security-model.md) for the complete guarantees and limitations.

## License

MIT