Gmail MCP Server

A Model Context Protocol (MCP) server that provides Gmail integration for AI assistants and chatbots.

Quick Start

# Install and run (requires Python 3.10+)
npx mcp-server-gmail

Features

• 📧 Send emails
• 📬 Read unread emails
• 🔍 Search emails by sender
• 📖 Read specific email content
• 🗑️ Move emails to trash
• ✅ Mark emails as read
• 🌐 Open emails in browser
• 🎯 AI-powered email drafting and management

Setup

1. Google Cloud Setup

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Gmail API:
   • Go to APIs & Services > Library
   • Search for "Gmail API"
   • Click Enable

2. OAuth 2.0 Credentials

1. Go to APIs & Services > Credentials
2. Click Create Credentials > OAuth client ID
3. Select Desktop application
4. Download the credentials file as credentials.json

3. Install and Setup

# Install the MCP server
npx mcp-server-gmail --help

# Create config directory and place credentials
mkdir -p ~/.gmail-mcp
cp /path/to/your/credentials.json ~/.gmail-mcp/credentials.json

4. First Run

# Start the server (will open browser for OAuth)
npx mcp-server-gmail

The first run will open a browser window for OAuth authentication. Grant the necessary permissions, and the server will store the tokens for future use.

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["-y", "mcp-server-gmail"]
    }
  }
}

Custom Paths

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "-y", 
        "mcp-server-gmail",
        "--creds-file-path", "/path/to/credentials.json",
        "--token-path", "/path/to/token.json"
      ]
    }
  }
}

Other MCP Hosts

For other MCP-compatible applications, use:

npx -y mcp-server-gmail

Available Tools

send-email

Send an email to a recipient.

Parameters:

• recipient_id (string): Email address of the recipient
• subject (string): Email subject
• message (string): Email body content

get-unread-emails

Retrieve all unread emails from your inbox.

read-email

Read the content of a specific email.

Parameters:

• email_id (string): The ID of the email to read

get-emails-by-sender

Get emails from a specific sender.

Parameters:

• sender_email (string): Email address of the sender
• unread_only (boolean, optional): Only fetch unread emails

trash-email

Move an email to trash.

Parameters:

• email_id (string): The ID of the email to trash

mark-as-read

Mark an email as read.

Parameters:

• email_id (string): The ID of the email to mark as read

open-email

Open an email in your default web browser.

Parameters:

• email_id (string): The ID of the email to open

Available Prompts

manage-email

Act as an email administrator with access to Gmail tools.

draft-email

Draft an email with specified content and recipient.

Arguments:

• content: What the email is about
• recipient: Who the email should be addressed to
• recipient_email: Recipient's email address

edit-draft

Edit an existing email draft.

Arguments:

• changes: What changes should be made to the draft
• current_draft: The current draft to edit

Usage Examples

With Claude Desktop

Once configured, you can ask Claude:

• "Check my unread emails"
• "Send an email to [email protected] about the meeting tomorrow"
• "Show me all emails from [email protected]"
• "Draft a professional email to the client about the project update"

Command Line Usage

# Basic usage
npx mcp-server-gmail

# Custom credentials path
npx mcp-server-gmail --creds-file-path /path/to/creds.json

# Custom token storage
npx mcp-server-gmail --token-path /path/to/token.json

# Help
npx mcp-server-gmail --help

Requirements

• Python 3.10+ (automatically checked during setup)
• Node.js 18+ (for npx)
• Google Cloud Project with Gmail API enabled
• OAuth 2.0 credentials for Gmail access

Troubleshooting

Python Not Found

# Install Python 3.12+
# macOS
brew install python3

# Ubuntu/Debian
sudo apt install python3

# Windows
# Download from python.org

OAuth Errors

1. Ensure Gmail API is enabled in Google Cloud Console
2. Check that OAuth consent screen is configured
3. Verify credentials file is valid JSON
4. Try deleting token file and re-authenticating

Permission Errors

The server requests minimal permissions:

• https://www.googleapis.com/auth/gmail.modify

This allows reading, sending, and managing emails but not deleting them permanently.

Security Notes

• Credentials and tokens are stored locally
• The server runs locally and doesn't send data to external services
• OAuth tokens are automatically refreshed as needed
• No email content is logged or stored beyond the session

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

Changelog

v0.1.0

• Initial release
• Basic Gmail integration
• Support for send, read, search, trash operations
• OAuth 2.0 authentication
• Cross-platform compatibility