Gmail MCP Server

# Gmail MCP Server <div align="center"> A powerful Model Context Protocol (MCP) server that enables Claude AI to directly interact with Gmail.  [](LICENSE)  </div> ## 📖 Table of Contents - [Overview](#overview) - [Key Features](#key-features) - [Quick Start](#quick-start) - [Prerequisites](#prerequisites) - [Installation](#installation) - [Set up Google Cloud and OAuth credentials](#set-up-google-cloud-and-oauth-credentials) - [First Run and Authentication](#first-run-and-authentication) - [Configure Claude Desktop](#configure-claude-desktop) - [Available Tools](#available-tools) - [Usage Examples](#usage-examples) - [Advanced Configuration](#advanced-configuration) - [Environment Variables](#environment-variables) - [SSE Server Mode](#sse-server-mode) - [Documentation](#documentation) - [Security Considerations](#security-considerations) - [Contributing](#contributing) - [License](#license) - [Acknowledgments](#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** ```bash git clone https://github.com/yourusername/gmail-mcp-server.git cd gmail-mcp-server ``` 2. **Set up a virtual environment** ```bash python -m venv venv # On Windows venv\Scripts\activate # On macOS/Linux source venv/bin/activate ``` 3. **Install dependencies** ```bash pip install -r requirements.txt ``` 4. **Set up Google Cloud and OAuth credentials** Visit the [Google Cloud Console](https://console.cloud.google.com/) 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: ```bash python gmail_server.py ``` 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: ```json { "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: ``` Send an email to john@example.com with the subject "Project Update" and let them know we're still on track for the deadline next week. ``` ``` Search my inbox for any emails from Bank of America in the last month and summarize them for me. ``` ``` Find all unread emails from my boss and create a summary of any action items mentioned in them. ``` ``` Draft an email to the team about the upcoming meeting on Thursday at 2pm. Remind everyone to prepare their weekly updates. ``` ## 🔧 Advanced Configuration ### Environment Variables The server supports multiple environment variables for customization: | Variable | Description | |----------|-------------| | `GMAIL_TOKEN_PATH` | Custom path to store OAuth token | | `GMAIL_CREDENTIALS_PATH` | Custom path to OAuth credentials | | `GOOGLE_CLIENT_ID` | OAuth client ID (alternative to credentials file) | | `GOOGLE_CLIENT_SECRET` | OAuth client secret (alternative to credentials file) | | `MCP_PORT` | Port for SSE transport (default: 3000) | | `DEBUG` | Enable debug mode (`true` or `false`) | ### SSE Server Mode The server can be run in SSE (Server-Sent Events) mode for HTTP-based integration: ```bash python gmail_server.py --sse [port] ``` This starts the server on the specified port (default: 3000), making it accessible via HTTP. ## 📚 Documentation - [MCP Specification](https://spec.modelcontextprotocol.io) - Learn about the Model Context Protocol - [Gmail API Documentation](https://developers.google.com/gmail/api/guides) - Reference for Gmail API capabilities - [Google Cloud OAuth](https://developers.google.com/identity/protocols/oauth2) - 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](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 --- <div align="center"> Made with ❤️ for the MCP and Claude community </div>