Enhanced Gmail MCP Server

A powerful and feature-rich Model Context Protocol (MCP) server for Gmail integration, written in Python. This server enables AI assistants like Claude to interact with Gmail through natural language, providing comprehensive email management capabilities.

🌟 Key Features

📧 Complete Email Management

Send emails with customizable subject, content, and recipients
Read and retrieve email content with full metadata
Move emails to trash with confirmation
Mark emails as read/unread
Open emails directly in browser

📝 Draft Management

Create draft emails for later review
List all draft emails
Edit existing drafts

🏷️ Advanced Label Management

List all available labels
Create custom labels
Apply/remove labels from emails
Rename existing labels
Delete unused labels
Search emails by label

📁 Folder Organization

Create new folders (implemented as Gmail labels)
Move emails between folders
List all available folders

🔍 Powerful Search & Filtering

Search emails using Gmail's advanced query syntax
Create, manage, and delete email filters
Filter by sender, recipient, subject, content, and more
Customize search results with flexible parameters

🗄️ Archive Management

Archive emails (remove from inbox without deleting)
Batch archive multiple emails matching search criteria
List all archived emails
Restore archived emails to inbox

🚀 Getting Started

Prerequisites

Python 3.8+
Google Cloud project with Gmail API enabled
OAuth 2.0 credentials

Installation

# Clone the repository
git clone https://github.com/theposch/gmail-mcp.git
cd gmail-mcp

# Set up a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package
pip install -e .

Google Cloud Setup

Create a new Google Cloud project
Enable the Gmail API
Configure the OAuth consent screen:
- Select "External" user type
- Add your email as a test user
- Add the scope: https://www.googleapis.com/auth/gmail/modify
Create OAuth 2.0 credentials:
- Choose "Desktop app" as the application type
- Download the JSON credentials file

Configuration

Store your credentials securely and specify their location when running the server:

# Example directory structure for credentials
mkdir -p ~/.gmail-mcp
# Move your downloaded credentials file
mv ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json

🔧 Usage

Running with Claude Desktop

Add the following to your Claude Desktop configuration file (typically at ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "gmail": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/gmail-mcp",
        "run",
        "gmail",
        "--creds-file-path",
        "/absolute/path/to/credentials.json",
        "--token-path",
        "/absolute/path/to/tokens.json"
      ]
    }
  }
}

Testing with MCP Inspector

For testing and debugging, use the MCP Inspector:

npx @modelcontextprotocol/inspector uv run /path/to/gmail-mcp/src/gmail/server.py --creds-file-path /path/to/credentials.json --token-path /path/to/tokens.json

🔐 Security Considerations

Never commit credentials or token files to version control
Store credentials in a secure location with appropriate permissions
The server will request user confirmation before performing sensitive actions
Review Google Cloud Console regularly for unusual activity
Consider using environment variables for sensitive paths

🛠️ Architecture

This implementation features a comprehensive single-file architecture that handles all Gmail operations through the Google API client libraries. Key components include:

OAuth2 authentication with automatic token refresh
Comprehensive error handling and logging
Structured tool definitions with clear input schemas
Efficient email parsing and formatting

📚 Example Prompts

Try these prompts with Claude after connecting the Gmail MCP server:

"Show me my unread emails"
"Search for emails from example@domain.com with attachments"
"Create a new label called 'Important Projects'"
"Draft an email to john@example.com about the upcoming meeting"
"Archive all emails from newsletter@example.com"
"Create a filter to automatically label emails from my team"

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the GPL-3.0 License - see the LICENSE file for details.

🙏 Acknowledgments

Inspired by various MCP server implementations in the community
Built with the Model Context Protocol framework
Uses Google's official API client libraries