email-mcp-server

tejaskumbhar288/email-mcp-server

3.2

If you are the rightful owner of email-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

An MCP server that provides email operations as tools for AI agents, enabling them to interact with emails using the Model Context Protocol.

Tools
4
Resources
0
Prompts
0

📧 Email Alert MCP Server

An MCP (Model Context Protocol) server that exposes email operations as tools for AI agents. This allows Claude or other LLM-based agents to naturally read, filter, send emails, and check unread counts through the MCP protocol.

🎯 Features

  • Read Emails: Fetch recent emails from your inbox
  • Filter Emails: Search emails by sender, subject, or unread status
  • Send Emails: Compose and send emails through your account
  • Unread Count: Check how many unread messages you have
  • Works with Gmail: Uses SMTP/IMAP for universal compatibility

🛠️ Prerequisites

  • Python 3.10 or higher
  • Gmail account with App Password enabled (see setup below)
  • Claude Desktop or any MCP-compatible client

📦 Installation

1. Clone or Navigate to the Project

cd "C:\Users\tejas\OneDrive\Desktop\Email MCP server"

2. Create Virtual Environment (if not already created)

python -m venv venv

3. Activate Virtual Environment

Windows:

venv\Scripts\activate

Mac/Linux:

source venv/bin/activate

4. Install Dependencies

pip install -r requirements.txt

🔐 Gmail Setup (App Password)

For security, Gmail requires an App Password instead of your regular password when using SMTP/IMAP.

Steps to Get Gmail App Password:

  1. Go to your Google Account: https://myaccount.google.com/
  2. Navigate to Security → 2-Step Verification (enable if not already enabled)
  3. Scroll down to App passwords
  4. Click Select app → Choose "Mail"
  5. Click Select device → Choose "Other" → Name it "MCP Server"
  6. Click Generate
  7. Copy the 16-character password (e.g., abcd efgh ijkl mnop)
  8. Update your .env file with this App Password

Update .env File

Your .env file should look like this:

EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-16-char-app-password

IMAP_SERVER=imap.gmail.com
SMTP_SERVER=smtp.gmail.com
IMAP_PORT=993
SMTP_PORT=587

OPENAI_API_KEY=your-openai-api-key (optional)

🚀 Running the Server

Test Locally

python server.py

The server will start and listen for MCP protocol messages via stdin/stdout.

🔧 Connecting to Claude Desktop

To use this MCP server with Claude Desktop, you need to add it to your Claude Desktop configuration.

1. Find Your Claude Config File

Mac:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

2. Add MCP Server Configuration

Edit the config file and add (see claude_desktop_config.example.json for reference):

{
  "mcpServers": {
    "email-alert": {
      "command": "python",
      "args": [
        "/absolute/path/to/your/project/server.py"
      ],
      "env": {
        "PYTHONPATH": "/absolute/path/to/your/project"
      }
    }
  }
}

Windows Example:

{
  "mcpServers": {
    "email-alert": {
      "command": "C:\\Users\\YourName\\path\\to\\venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\YourName\\path\\to\\Email MCP server\\server.py"
      ]
    }
  }
}

Mac/Linux Example:

{
  "mcpServers": {
    "email-alert": {
      "command": "/usr/bin/python3",
      "args": [
        "/home/username/Email-MCP-server/server.py"
      ]
    }
  }
}

Note: Replace paths with your actual project location.

3. Restart Claude Desktop

Close and reopen Claude Desktop to load the new MCP server.

🧪 Testing the Tools

Once connected to Claude Desktop, you can test the email tools with natural language:

Examples:

Check Unread Emails:

"How many unread emails do I have?"

Read Recent Emails:

"Show me my 5 most recent emails"

Filter by Sender:

"Show me all emails from john@example.com"

Search by Subject:

"Find emails with 'meeting' in the subject"

Send an Email:

"Send an email to sangeeta@example.com with subject 'Meeting Reminder' and tell her about the 4 PM meeting"

🔧 Available MCP Tools

1. read_emails

Read recent emails from inbox or specified folder.

Parameters:

  • count (number, optional): Number of emails to retrieve (default: 10)
  • folder (string, optional): Email folder (default: "INBOX")

2. filter_emails

Search and filter emails by criteria.

Parameters:

  • sender (string, optional): Filter by sender email address
  • subject (string, optional): Filter by subject (substring match)
  • is_unread (boolean, optional): Filter by unread status
  • folder (string, optional): Email folder (default: "INBOX")

3. send_email

Send an email to a recipient.

Parameters:

  • to (string, required): Recipient email address
  • subject (string, required): Email subject line
  • body (string, required): Email body content
  • cc (string, optional): CC recipient email address

4. get_unread_count

Get count of unread emails.

Parameters:

  • folder (string, optional): Email folder (default: "INBOX")

🏗️ Project Structure

Email MCP server/
├── server.py              # Main MCP server
├── email_client.py        # Email operations (SMTP/IMAP)
├── requirements.txt       # Python dependencies
├── .env                   # Environment variables (NOT in git)
├── .env.example          # Example environment file
├── .gitignore            # Git ignore rules
└── README.md             # This file

🔒 Security Notes

⚠️ Important:

  1. Never commit .env file - It contains sensitive credentials
  2. Use App Passwords - Never use your main Gmail password
  3. Restrict Access - Keep your MCP server local and trusted
  4. Monitor Usage - Review sent emails periodically

📤 Pushing to GitHub

✅ Safe to Push:

  • server.py - Your MCP server code
  • email_client.py - Email operations
  • test_email.py - Testing script
  • requirements.txt - Dependencies list
  • README.md - Documentation
  • .env.example - Template (NO real credentials)
  • claude_desktop_config.example.json - Config template
  • .gitignore - Git ignore rules

❌ NEVER Push:

  • .env - Contains your email password! (Auto-ignored)
  • claude_desktop_config.json - Has your specific paths (Auto-ignored)
  • venv/ - Virtual environment folder (Auto-ignored)
  • __pycache__/ - Python cache (Auto-ignored)

The .gitignore file is already configured to protect sensitive files.

🐛 Troubleshooting

"Authentication failed" Error

  • Make sure you're using a Gmail App Password, not your regular password
  • Verify 2-Step Verification is enabled on your Google account
  • Check that EMAIL_USER and EMAIL_PASS in .env are correct

"Connection refused" Error

  • Check your internet connection
  • Verify firewall isn't blocking SMTP (port 587) or IMAP (port 993)
  • Ensure Gmail hasn't flagged your account for suspicious activity

"MCP server not showing in Claude Desktop"

  • Verify the path in claude_desktop_config.json is correct
  • Check that Python is in your system PATH
  • Restart Claude Desktop after config changes
  • Check Claude Desktop logs for errors

📚 Learn More

📝 License

MIT License - Feel free to use and modify!

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

Built with ❤️ using the Model Context Protocol