# Universal Mail MCP Server

> **⚠️ BETA SOFTWARE:** This project is in beta and has not been fully tested. Use at your own risk. Please report any issues on GitHub.

A cross-platform MCP (Model Context Protocol) server that provides Claude with email access via IMAP. Works on **macOS, Windows, and Linux** with any IMAP-compatible email provider.

## Platform Support

| Platform | Supported | Notes |
|----------|-----------|-------|
| macOS | ✅ Yes | Full support |
| Windows | ✅ Yes | Full support |
| Linux | ✅ Yes | Full support |

### Supported Email Providers

| Provider | IMAP Server | Notes |
|----------|-------------|-------|
| Gmail | imap.gmail.com | Requires App Password if 2FA enabled |
| Outlook/Microsoft 365 | outlook.office365.com | Works with work/personal accounts |
| iCloud | imap.mail.me.com | Requires App-Specific Password |
| Yahoo | imap.mail.yahoo.com | Requires App Password |
| Any IMAP server | Custom | Enter server details manually |

## Features

### Email Reading & Search

| Tool | Description |
|------|-------------|
| `mail_list_accounts` | List all configured email accounts |
| `mail_list_mailboxes` | List mailboxes/folders for an account |
| `mail_get_messages` | Get messages from a mailbox with filters |
| `mail_search` | Search emails by subject, sender, or both |
| `mail_get_message_detail` | Get full details of a specific email |
| `mail_unread_count` | Get unread counts by account |
| `mail_get_important` | Get flagged emails |

### Email Management

| Tool | Description |
|------|-------------|
| `mail_mark_read` | Mark messages as read/unread |
| `mail_flag_message` | Flag/unflag messages |
| `mail_delete_by_sender` | Bulk delete emails from specific senders |

### Direct Mail Links

All message-returning tools include `message_url` for opening emails directly:

```json
{
  "id": "12345",
  "message_id": "<abc123@mail.gmail.com>",
  "message_url": "message://%3Cabc123%40mail.gmail.com%3E",
  "subject": "Your order has shipped",
  "sender": "orders@amazon.com"
}
```

## Requirements

- **Python** 3.10 or later
- **pip** (Python package manager)
- **Claude Desktop** or Claude Code CLI

## Installation

### 1. Clone the repository

```bash
git clone https://github.com/oscar23445/universal-mail-mcp.git
cd universal-mail-mcp
```

### 2. Install the package

```bash
pip install -e .
```

Or install dependencies directly:

```bash
pip install mcp keyring
```

### 3. Configure your email accounts

Run the interactive setup:

```bash
universal-mail-mcp --setup
```

This will:
- Prompt for account details (name, email, IMAP server)
- Store passwords securely in your system's keyring
- Test the connection

**Example setup:**
```
Account name: personal
Email address: you@gmail.com
Provider: gmail
Password or App Password: xxxx-xxxx-xxxx-xxxx

✓ Account 'personal' saved successfully!
```

### 4. Test the server

```bash
universal-mail-mcp
```

You should see: `Universal Mail MCP Server running on stdio`

Press `Ctrl+C` to stop.

### 5. Configure Claude Desktop

Edit your Claude Desktop config file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**Linux:** `~/.config/Claude/claude_desktop_config.json`

Add the server:

```json
{
  "mcpServers": {
    "universal-mail": {
      "command": "universal-mail-mcp"
    }
  }
}
```

Or if using Python directly:

```json
{
  "mcpServers": {
    "universal-mail": {
      "command": "python",
      "args": ["-m", "universal_mail_mcp.server"]
    }
  }
}
```

### 6. Restart Claude Desktop

Quit and reopen Claude Desktop. The mail tools will be available.

## Gmail Setup

Gmail requires an **App Password** if you have 2-Factor Authentication enabled:

1. Go to [Google Account Security](https://myaccount.google.com/security)
2. Enable 2-Step Verification if not already enabled
3. Go to [App Passwords](https://myaccount.google.com/apppasswords)
4. Create a new App Password for "Mail"
5. Use this 16-character password in the setup

## iCloud Setup

iCloud requires an **App-Specific Password**:

1. Go to [Apple ID](https://appleid.apple.com)
2. Sign in and go to Security
3. Under "App-Specific Passwords", click "Generate Password"
4. Use this password in the setup

## Credential Storage

Passwords are stored securely using your system's native keyring:

| Platform | Keyring Backend |
|----------|-----------------|
| macOS | Keychain |
| Windows | Windows Credential Manager |
| Linux | Secret Service (GNOME Keyring, KWallet) |

Account configurations (non-sensitive) are stored in:
- macOS: `~/Library/Application Support/universal-mail-mcp/accounts.json`
- Windows: `%APPDATA%/universal-mail-mcp/accounts.json`
- Linux: `~/.config/universal-mail-mcp/accounts.json`

## Usage Examples

### Basic queries
- "How many unread emails do I have?"
- "Show me unread emails from my work account"
- "Search for emails from Amazon"
- "What are my flagged emails?"

### Email management
- "Mark that email as read"
- "Flag that email for follow-up"
- "Delete all emails from spam@example.com"

### Multi-account
- "List my email accounts"
- "Show unread count for each account"
- "Search for 'invoice' across all accounts"

## Troubleshooting

### "No email accounts configured"
Run the setup wizard:
```bash
universal-mail-mcp --setup
```

### "Credentials not found"
Re-run setup to store credentials:
```bash
universal-mail-mcp --setup
```
Choose option 1 to add the account again.

### Gmail: "Invalid credentials"
- Ensure you're using an App Password, not your regular password
- Check that "Less secure app access" is enabled (if not using App Password)
- Verify 2FA status at https://myaccount.google.com/security

### Connection timeout
- Verify your IMAP server and port are correct
- Check your firewall allows outbound connections on port 993
- Some corporate networks block IMAP

### Linux: Keyring issues
Install the secret service:
```bash
# Ubuntu/Debian
sudo apt install gnome-keyring

# Fedora
sudo dnf install gnome-keyring
```

## Privacy & Security

- All processing happens locally on your machine
- No emails are sent to external servers
- Credentials are stored in your system's secure keyring
- Claude only sees what you explicitly request
- Destructive operations (`mail_delete_by_sender`) are clearly marked

## Development

### Project Structure

```
universal-mail-mcp/
├── src/
│   └── universal_mail_mcp/
│       ├── __init__.py
│       ├── server.py          # MCP server
│       ├── credentials.py     # Secure credential storage
│       └── backends/
│           ├── __init__.py
│           └── imap.py        # IMAP backend
├── pyproject.toml
├── README.md
└── LICENSE
```

### Running from source

```bash
# Clone
git clone https://github.com/oscar23445/universal-mail-mcp.git
cd universal-mail-mcp

# Install in development mode
pip install -e ".[dev]"

# Run
python -m universal_mail_mcp.server
```

### Running tests

```bash
pytest
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests (`pytest`)
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Author

OES Software LLC

## Related Projects

- [apple-mail-mcp-server](https://github.com/oscar23445/apple-mail-mcp-server) - macOS-only Apple Mail integration using AppleScript
- [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic