Gmail MCP Server

A powerful Model Context Protocol (MCP) server that enables Claude AI to directly interact with Gmail.

📖 Table of Contents

• Overview

• Key Features

• Quick Start

  • Prerequisites

  • Installation

  • Set up Google Cloud and OAuth credentials

  • First Run and Authentication

  • Configure Claude Desktop

• Available Tools

• Usage Examples

• Advanced Configuration

  • Environment Variables

  • SSE Server Mode

• Documentation

• Security Considerations

• Contributing

• License

• Acknowledgments

📋 Overview

The Gmail MCP Server is a comprehensive implementation that enables AI assistants like Claude to directly interact with Gmail through natural language. It exposes a rich set of tools for email management, enabling seamless integration between conversational AI and your inbox.

💡 Key Features

• Complete Email Management

  • Send plain text and HTML emails with attachments

  • Read emails with proper parsing of complex message structures

  • Search your inbox with Gmail's powerful query syntax

  • Create and update draft emails

  • Manage labels, read/unread status, and trash

  • Perform batch operations on multiple emails

• Advanced Integration

  • Modern Python codebase with async/await pattern

  • Comprehensive error handling and recovery

  • Detailed progress reporting

  • Secure OAuth authentication flow

  • Multiple transport modes (STDIO and SSE)

  • Support for different deployment scenarios

🚀 Quick Start

Prerequisites

• Python 3.8 or higher

• A Google Cloud project with the Gmail API enabled

• OAuth 2.0 credentials for the Gmail API

Installation

1. Clone the repository

   git clone https://github.com/yourusername/gmail-mcp-server.git cd gmail-mcp-server

2. Set up a virtual environment

   python -m venv venv # On Windows venv\Scripts\activate # On macOS/Linux source venv/bin/activate

3. Install dependencies

   pip install -r requirements.txt

4. Set up Google Cloud and OAuth credentials

   Visit the Google Cloud Console to:

   • Create a new project

   • Enable the Gmail API

   • Set up OAuth consent screen

   • Create OAuth Client ID credentials (Desktop application)

   • Download credentials as credentials.json in project root

First Run and Authentication

Run the server once to authenticate:

This will open a browser window asking you to authenticate with your Google account. After authentication, a token.json file will be created and saved for future use.

Configure Claude Desktop

1. Edit your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the Gmail MCP server to the configuration:

   { "mcpServers": { "gmail": { "command": "python", "args": [ "/absolute/path/to/gmail-mcp-server/gmail_server.py" ] } } }

3. Save the file and restart Claude Desktop

Note: Replace "/absolute/path/to/gmail-mcp-server/gmail_server.py" with the actual absolute path to the gmail_server.py file in your cloned repository.

🧰 Available Tools

The Gmail MCP Server exposes the following tools to Claude:

Email Sending

• send_email - Send basic emails with text/HTML content

• send_email_with_attachment - Send emails with file attachments

• send_email_with_multiple_attachments - Send emails with multiple attachments

Email Reading

• read_email - Read the content of a specific email by ID

• get_unread_emails - Get a list of unread emails

• get_important_emails - Get emails marked as important

• get_emails_with_attachments - Get emails that have attachments

• get_recent_emails - Get emails from the last X days

Email Search and Organization

• search_emails - Search emails using Gmail's query syntax

• get_email_labels - List all Gmail labels/folders

• create_email_label - Create a new label

• delete_email_label - Delete an existing label

• label_email - Apply a label to an email

• remove_email_label - Remove a label from an email

Email Status Management

• mark_as_read - Mark an email as read

• mark_as_unread - Mark an email as unread

• delete_email - Move an email to trash

Draft Management

• create_email_draft - Create a new draft email

• update_email_draft - Update an existing draft

• list_email_drafts - List available drafts

• send_draft - Send an existing draft

Batch Operations

• batch_apply_label - Apply a label to multiple emails

• batch_delete_emails - Move multiple emails to trash

Account Information

• get_email_profile - Get Gmail profile information

• summarize_recent_emails - Create a summary of recent emails

💬 Usage Examples

Here are some example prompts for Claude:

🔧 Advanced Configuration

Environment Variables

The server supports multiple environment variables for customization:

SSE Server Mode

The server can be run in SSE (Server-Sent Events) mode for HTTP-based integration:

This starts the server on the specified port (default: 3000), making it accessible via HTTP.

📚 Documentation

• MCP Specification - Learn about the Model Context Protocol

• Gmail API Documentation - Reference for Gmail API capabilities

• Google Cloud OAuth - Details on authentication flows

🔒 Security Considerations

• The server uses OAuth 2.0 for secure Gmail API authentication

• All actions run locally on your machine - emails never pass through third-party servers

• Authentication tokens are stored locally and can be revoked at any time

• The server requires local file access only for reading attachments

• Claude always asks for confirmation before sending or deleting emails

🤝 Contributing

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

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add some amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

📝 License

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

🙏 Acknowledgments

• Google for the Gmail API

• Anthropic for Claude and the Model Context Protocol

• Contributors to the Python Gmail API client libraries