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:

{
  "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

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

2. Install the package

pip install -e .

Or install dependencies directly:

pip install mcp keyring

3. Configure your email accounts

Run the interactive setup:

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

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:

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

Or if using Python directly:

{
  "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:

Go to Google Account Security
Enable 2-Step Verification if not already enabled
Go to App Passwords
Create a new App Password for "Mail"
Use this 16-character password in the setup

iCloud Setup

iCloud requires an App-Specific Password:

Go to Apple ID
Sign in and go to Security
Under "App-Specific Passwords", click "Generate Password"
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

# 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

pytest

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests (pytest)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT License - see LICENSE file for details.

Author

OES Software LLC

Related Projects

apple-mail-mcp-server - macOS-only Apple Mail integration using AppleScript
Model Context Protocol by Anthropic

universal-mail-mcp