s-morgan-jeffries/apple-mail-mcp
If you are the rightful owner of apple-mail-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The Apple Mail MCP Server provides programmatic access to Apple Mail, enabling AI assistants to manage emails on macOS.
Apple Mail MCP Server
A Model Context Protocol (MCP) server that provides programmatic access to Apple Mail, enabling AI assistants like Claude to read, send, search, and manage emails on macOS.
Features
Phase 1 (v0.1.0) - Current
- š Search messages with filters (sender, subject, read status, date range)
- š§ Send emails with confirmation prompts
- š¬ Read messages with full content and metadata
- š List mailboxes and folder structure
- ā Mark as read/unread
Coming Soon
- Phase 2 (v0.2.0): Attachments, moving messages, flags, threads
- Phase 3 (v0.3.0): Reply/forward, bulk operations, templates
- Phase 4 (v0.4.0): Analytics, multi-account, advanced workflows
Installation
Prerequisites
- macOS 10.15 (Catalina) or later
- Python 3.10 or later
- Apple Mail configured with at least one account
Install from PyPI
pip install apple-mail-mcp
Install from source
git clone https://github.com/morgancoopercom/apple-mail-mcp.git
cd apple-mail-mcp
pip install -e ".[dev]"
Configuration
Claude Desktop
Add to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"apple-mail": {
"command": "python",
"args": ["-m", "apple_mail_mcp.server"]
}
}
}
Permissions
On first use, macOS will prompt you to grant permissions:
- Automation: Allow the MCP server to control Apple Mail
- Full Disk Access (optional): Only needed for analytics features in Phase 4
Usage
Once configured, you can interact with Apple Mail through Claude Desktop using natural language:
Examples
Search emails:
Find all unread emails from john@example.com in the last week
Read messages:
Show me the content of the most recent email from my manager
Send email:
Draft an email to alice@example.com thanking her for the meeting
Manage folders:
List all my mailboxes and show unread counts
Mark as read:
Mark all newsletters from this week as read
Available Tools
search_messages
Search for messages with various filters.
Parameters:
account
(required): Account name (e.g., "Gmail", "iCloud")mailbox
(optional): Mailbox name (default: "INBOX")sender_contains
(optional): Filter by sender email/domainsubject_contains
(optional): Filter by subject keywordsread_status
(optional): Filter by read/unread statusdate_from
(optional): Start date for date rangedate_to
(optional): End date for date rangelimit
(optional): Maximum results to return
get_message
Get full details of a specific message.
Parameters:
message_id
(required): Message ID from search resultsinclude_content
(optional): Include message body (default: true)
send_email
Send an email via Apple Mail.
Parameters:
subject
(required): Email subjectbody
(required): Email body (plain text)to
(required): List of recipient email addressescc
(optional): List of CC recipientsbcc
(optional): List of BCC recipients
Security: All send operations require user confirmation.
list_mailboxes
List all mailboxes and folders for an account.
Parameters:
account
(required): Account name
mark_as_read
Mark messages as read or unread.
Parameters:
message_ids
(required): List of message IDsread
(optional): true for read, false for unread (default: true)
Security
This MCP server prioritizes security and user control:
- ā Local execution: All operations run locally on your machine
- ā User confirmation: Sending emails requires explicit approval
- ā Input sanitization: All inputs are validated and escaped
- ā Audit logging: Operations are logged for transparency
- ā No credential storage: Uses existing Mail.app authentication
- ā Read-only by default: Destructive operations require confirmation
Attack Surface Considerations
When using an MCP connector with your local Mail account:
- Prompt injection: Malicious email content could influence AI behavior
- Mitigation: User confirmation for sensitive operations
- Data exfiltration: Email content is accessible to Claude
- Mitigation: Local processing, no cloud sync beyond Claude API
- Unintended actions: Bugs could cause unwanted operations
- Mitigation: Confirmation prompts, rate limiting, comprehensive tests
Development
Setup Development Environment
# Clone repository
git clone https://github.com/morgancoopercom/apple-mail-mcp.git
cd apple-mail-mcp
# Create virtual environment
python -m venv venv
source venv/bin/activate # or `venv\Scripts\activate` on Windows
# Install with dev dependencies
pip install -e ".[dev]"
Running Tests
# Run all tests
pytest
# Run with coverage
pytest --cov
# Run specific test file
pytest tests/unit/test_mail_connector.py
# Run integration tests (requires Mail.app setup)
pytest tests/integration/
Code Quality
# Format code
black src/ tests/
# Lint
ruff check src/ tests/
# Type check
mypy src/
Test-Driven Development
This project uses TDD throughout:
- Write test first (red)
- Implement minimal code to pass (green)
- Refactor for quality (refactor)
- Repeat
See for examples.
Architecture
Components
apple-mail-mcp/
āāā server.py # FastMCP server implementation
āāā mail_connector.py # AppleScript interface
āāā tools.py # MCP tool implementations
āāā security.py # Input validation, confirmations
āāā utils.py # Helper functions
How It Works
- MCP Protocol: Claude Desktop communicates with the server via JSON-RPC
- AppleScript Bridge: Python executes AppleScript commands via
osascript
- Mail.app: AppleScript controls Mail.app to perform operations
- Response: Results are returned to Claude as structured data
Performance
- Search: ~1-5 seconds for typical mailboxes (1000s of messages)
- Send: ~1-2 seconds
- Read: <1 second per message
- Optimization: Uses AppleScript
whose
clauses for efficient filtering
Roadmap
- v0.1.0: Core search, read, send functionality
- v0.2.0: Attachments, moving messages, flags, threads
- v0.3.0: Reply/forward, bulk operations, templates
- v0.4.0: Analytics, multi-account, SQLite integration
See GitHub Issues for detailed planning.
Contributing
Contributions welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature
) - Write tests for new functionality
- Ensure all tests pass (
pytest
) - Commit changes (
git commit -m 'Add amazing feature'
) - Push to branch (
git push origin feature/amazing-feature
) - Open a Pull Request
License
MIT License - see for details.
Acknowledgments
- Built with FastMCP by Jeremiah Lowin
- Uses Apple Mail's AppleScript interface
- Inspired by the MCP Protocol by Anthropic
Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation:
Related Projects
- supermemoryai/apple-mcp - TypeScript Apple ecosystem MCP
- 54yyyu/pyapple-mcp - Python Apple system MCP
- loopwork/iMCP - Swift native MCP implementation