# Apple Mail Summary MCP Server

A Model Context Protocol (MCP) server for macOS that allows AI agents to interact with the local **Apple Mail** application. This server enables LLMs to fetch emails from specific accounts and mailboxes, and includes specialized tools for parsing academic paper alerts.

## Features

- 📧 **Fetch Emails**: Retrieve the latest unread emails from any configured Apple Mail account and mailbox.
- 🎓 **Scholar Tools**: specialized parsing for Google Scholar Alert emails to extract paper titles and links.
- 🔒 **Local & Secure**: Runs locally on your machine, communicating directly with Apple Mail via AppleScript.

## Prerequisites

- **macOS**: This server relies on `osascript` (AppleScript) to communicate with Apple Mail. It **will not work** on Windows or Linux.
- **Apple Mail**: Must be set up and running with your email accounts configured.
- **Python 3.10+**
- **uv** (recommended for package management) or standard pip.

## Usage

### 1. Identify your Mail Configuration

To use this server, you need to know the exact names of your **Accounts** and **Mailboxes** as they appear in Apple Mail.

You can find these by hovering over the mailbox in the Mail app sidebar, or by running this simple AppleScript in 'Script Editor.app':

```applescript
tell application "Mail"
    get name of every account
end tell
```

### 2. Environment Variables (Optional)

You can set default values for the account and mailbox using environment variables. This allows the AI agent to skip specifying these parameters every time.

| Variable | Description | Default |
|----------|-------------|---------|
| `APPLE_MAIL_SUMMARY_MCP_ACCOUNT` | The name of the default Apple Mail account. | None (Required if not provided via tool) |
| `APPLE_MAIL_SUMMARY_MCP_MAILBOX` | The name of the default mailbox. | `Inbox` |

### 3. Configuration for Claude Desktop

You can add this server to your `claude_desktop_config.json` in two ways:

#### Option A: Running directly from GitHub via `uvx` (No manual install needed)
This is the easiest way to try it out without manually cloning the repo.

```json
{
  "mcpServers": {
    "apple-mail-summary": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/BillShiyaoZhang/apple-mail-summary-mcp.git", 
        "apple-mail-summary-mcp" 
      ],
      "env": {
        "APPLE_MAIL_SUMMARY_MCP_ACCOUNT": "Your Default Account Name",
        "APPLE_MAIL_SUMMARY_MCP_MAILBOX": "Inbox"
      }
    }
  }
}
```

#### Option B: Running from a Local Clone (Development)

If you want to run from a local copy or make changes, first clone the repository and install dependencies:

**Using uv (Recommended)**

```bash
git clone https://github.com/BillShiyaoZhang/apple-mail-summary-mcp.git
cd apple-mail-summary-mcp
uv pip install -e .
```

**Using pip**

```bash
git clone https://github.com/BillShiyaoZhang/apple-mail-summary-mcp.git
cd apple-mail-summary-mcp
pip install -e .
```

Then configure your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "apple-mail-summary": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/apple-mail-summary-mcp",
        "run",
        "apple-mail-summary-mcp"
      ]
    }
  }
}
```

> **Note**: For Option B to work, make sure `uv` is in your system PATH.

### 3. Running the Server Manually
You can also run the server directly if needed:
```bash
python -m apple_mail_summary_mcp.server
```

### 4. Available Tools

#### `fetch_emails(account: str = None, mailbox: str = None, limit: int = 5)`
Fetches a list of unread emails from a specific source.
- **account**: The exact name of the account (e.g., "iCloud", "Exchange", "Personal"). Defaults to `APPLE_MAIL_SUMMARY_MCP_ACCOUNT` if not provided.
- **mailbox**: The mailbox name (e.g., "Inbox", "Spam", "Google Scholar"). Defaults to `APPLE_MAIL_SUMMARY_MCP_MAILBOX` (or "Inbox") if not provided.
- **limit**: Maximum number of emails to retrieve.

#### `extract_scholar_links(html_content: str)`
A utility tool to parse the HTML content of a Google Scholar Alert email and return structured data (Title, URL).
- **html_content**: The raw HTML body of the email.

## Development

Project structure:
- `src/apple_mail_summary_mcp/email_client.py`: Handles AppleScript communication.
- `src/apple_mail_summary_mcp/processor.py`: Contains HTML parsing logic (BeautifulSoup).
- `src/apple_mail_summary_mcp/server.py`: Defines the FastMCP server and tools.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

[MIT](LICENSE)