@cristip73/email-mcp v0.8.0

MCP Gmail Server

A Model Context Protocol (MCP) server that enables Claude Desktop App and other MCP-compatible applications to interact with Gmail. This package provides capabilities for reading, searching, and sending emails through a standardized interface.

Features

• Core Email Operations: Send emails, replies, forwards, read and search emails
• Advanced Features: Reply-all, CC/BCC, quoted replies, threading, attachments, drafts
• Gmail-Specific: Category management (Primary, Social, Promotions, etc.)
• Label Management: Create, modify, list, and apply Gmail labels
• Attachment Handling: List and save email attachments securely
• Time Zone Support: Proper date/time handling based on your local timezone

Quick Start

Installation & Authentication

# Run with npx (no installation needed)
npx @cristip73/email-mcp auth

# This will open a browser window for Gmail authentication

Configuration with Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "email-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cristip73/email-mcp"
      ],
      "env": {
        "TIME_ZONE": "GMT+2",
        "DEFAULT_ATTACHMENTS_FOLDER": "/Users/username/CLAUDE/Attachments"
      }     
    }
  }
}

Prerequisites

• Node.js 16 or higher
• A Google Cloud project with Gmail API enabled
• OAuth credentials for a Desktop application
• A Gmail account

Detailed Setup

For detailed setup instructions including OAuth configuration, see INSTALL.md.

Environment Variables

• TIME_ZONE: Your timezone in GMT format (e.g., GMT+2)
• DEFAULT_ATTACHMENTS_FOLDER: Path for saving attachments
• GMAIL_OAUTH_PATH: Custom path to OAuth credentials file
• GMAIL_CREDENTIALS_PATH: Custom path to tokens file

File Locations

The configuration files are stored in your home directory:

• OAuth Credentials: ~/.email-mcp/gcp-oauth.keys.json

  • macOS: /Users/[username]/.email-mcp/gcp-oauth.keys.json
  • Linux: /home/[username]/.email-mcp/gcp-oauth.keys.json
  • Windows: C:\Users\[username]\.email-mcp\gcp-oauth.keys.json

• Auth Tokens: ~/.email-mcp/credentials.json

  • macOS: /Users/[username]/.email-mcp/credentials.json
  • Linux: /home/[username]/.email-mcp/credentials.json
  • Windows: C:\Users\[username]\.email-mcp\credentials.json

The .email-mcp directory is hidden but will be created automatically.

Full Documentation

For complete documentation, available tools, and example prompts, see the full README.

License

MIT