gmail-mcp-imap

A Gmail MCP (Model Context Protocol) server that provides email management capabilities through IMAP/SMTP. Works with Claude Desktop, Claude Code, and any MCP-compatible client.

Features

• Gmail Categories: Fetch emails by Gmail's smart categories (Primary, Social, Promotions, Updates, Forums)

• Full Email Management: Read, send, reply, star, delete, and label emails

• Attachment Handling: List, download, and save attachments to disk

• No Google API Required: Uses IMAP/SMTP directly with App Password authentication

• Date Filtering: Filter emails by date range

Related MCP server: IMAP MCP Server

Installation

npm install gmail-mcp-imap

Or run directly with npx:

npx gmail-mcp-imap

Prerequisites

1. A Gmail account

2. App Password (not your regular password):

   • Go to Google Account Security

   • Enable 2-Step Verification if not already enabled

   • Go to App Passwords (search for "App Passwords" in account settings)

   • Generate a new app password for "Mail"

   • Copy the 16-character password

Configuration

Environment Variables

Set these environment variables before running:

export GMAIL_EMAIL="your-email@gmail.com"
export GMAIL_APP_PASSWORD="your-16-char-app-password"

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["gmail-mcp-imap"],
      "env": {
        "GMAIL_EMAIL": "your-email@gmail.com",
        "GMAIL_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

Claude Code Configuration

Add to your .mcp.json:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["gmail-mcp-imap"],
      "env": {
        "GMAIL_EMAIL": "your-email@gmail.com",
        "GMAIL_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

Available Tools

Category Tools

Search & Read Tools

Action Tools

Attachment Tools

Usage Examples

Once configured, you can ask Claude:

• "Show me my primary emails from the last week"

• "Search for emails from Amazon"

• "Read the email with UID 12345"

• "Send an email to john@example.com about the meeting"

• "Download the PDF attachment from email 12345"

• "Star the important emails about invoices"

Why IMAP/SMTP?

This MCP server uses IMAP/SMTP instead of the Google API because:

1. Simpler Setup: No OAuth consent screen or API credentials needed

2. App Passwords: More secure than storing your main password

3. No Rate Limits: Google API has strict quotas; IMAP doesn't

4. Works Offline: No dependency on Google's API servers

5. Privacy: Your emails aren't processed through additional Google services

Development

# Clone the repository
git clone https://github.com/suhail-ak-2/gmail-mcp-imap.git
cd gmail-mcp

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run production build
npm start

License

MIT

Author

Suhail (@ansuhail.ak@gmail.com)