Gmail MCP

A Model Context Protocol (MCP) server for Gmail operations using IMAP/SMTP with app password authentication.

Features

• listMessages: List the last 10 messages (or more if specified)
• findMessage: Search for messages containing specific words or phrases
• sendMessage: Send emails with specified recipient and message body

Simple Setup (No OAuth Required!)

1. Gmail App Password Setup

1. Enable 2-Factor Authentication on your Gmail account
2. Go to Google Account Settings → Security → App passwords
3. Generate an App password for “Mail”
4. Copy the 16-character app password

2. Local Development

1. Install dependencies:

   npm install
   

2. Create a .env file:

   [email protected]
   EMAIL_PASSWORD=your_16_char_app_password
   IMAP_HOST=imap.gmail.com
   IMAP_PORT=993
   SMTP_HOST=smtp.gmail.com
   SMTP_PORT=587
   

3. Build and start:

   npm run build
   npm start
   

3. Docker Usage

1. Create your .env file (as above)

2. Build and run:

   npm run docker:build
   docker run --rm -i --env-file .env email-mcp-server
   

MCP Client Integration

Simple Docker Configuration

Add this to your MCP client settings:

{
  "mcpServers": {
    "email": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", ".env",
        "email-mcp-server"
      ]
    }
  }
}

Using with Docker Compose

{
  "mcpServers": {
    "email": {
      "command": "docker-compose",
      "args": ["run", "--rm", "email-mcp-server"]
    }
  }
}

Supported Email Providers

Gmail (Default)

• IMAP: imap.gmail.com:993 (SSL)
• SMTP: smtp.gmail.com:587 (TLS)
• Requires: App password (not regular password)

Outlook/Hotmail

Update .env:

IMAP_HOST=outlook.office365.com
SMTP_HOST=smtp-mail.outlook.com

Other Providers

Just update the IMAP/SMTP settings in your .env file!

Usage Examples

List Recent Messages

{
  "count": 20
}

Search Messages

{
  "query": "important meeting"
}

Send Email

{
  "to": "[email protected]",
  "subject": "Hello from MCP!",
  "body": "This email was sent via the Email MCP Server"
}

Why IMAP/SMTP vs Gmail API?

✅ IMAP/SMTP Advantages:

• Simple app password authentication
• Works with any email provider
• No OAuth2 complexity
• No Google Cloud Console setup
• Immediate setup (2 minutes)

❌ Gmail API Disadvantages:

• Complex OAuth2 flow
• Google Cloud Console configuration
• Token management and refresh
• Gmail-only (vendor lock-in)

Usage with Claude Desktop

Configuration

1. Add the MCP server configuration to your Claude Desktop config file:
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json