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:

1. Go to Google Account Security
2. Enable 2-Step Verification if not already enabled
3. Go to App Passwords
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
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:

universal-mail-mcp --setup

"Credentials not found"

Re-run setup to store credentials:

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:

# 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

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