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

Supported Email Providers

Related MCP server: mcp-email

Features

Email Reading & Search

Email Management

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:

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