Gmail

🚀 Gmail MCP Server

A Model Context Protocol (MCP) server that provides Gmail integration for MCP clients like Claude Desktop.

🚀 Quick Start

The Gmail MCP Server is a powerful tool that integrates Gmail functionality into MCP clients such as Claude Desktop. It allows users to access and search their Gmail inbox directly from the client, enhancing productivity and convenience.

✨ Features

• View recent emails in your Gmail inbox.
• Search for emails using Gmail's search syntax.
• Secure authentication with the Gmail API via OAuth2.

📦 Installation

1. Google Cloud Project Setup

1. Create a Google Cloud project at https://console.cloud.google.com/.
2. Enable the Gmail API.
3. Create OAuth 2.0 credentials:
   • Application type: Desktop app
   • Download the credentials as credentials.json.

2. Package Installation

# Create a conda environment
conda create -n mcp-gmail python=3.12
conda activate mcp-gmail

# Install the package
cd gmail-mcp-server
pip install -e .

3. Configuration for Claude Desktop

Add the following content to your claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/conda/envs/mcp-gmail/bin/python",
      "args": ["-m", "gmail_mcp_server.server"],
      "env": {
        "PYTHONPATH": "/path/to/gmail-mcp-server/src",
        "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json",
        "GMAIL_TOKEN_FILE": "/path/to/token.json"
      }
    }
  }
}

Replace /path/to/ with your actual paths. The token file will be created automatically during the first authentication.

4. First Run

When you first attempt to access Gmail through Claude, you will be prompted in your browser to authorize the application. After authorization, the credentials will be saved to the token file for future use.

💻 Usage Examples

Available Resources

• gmail://inbox/recent - Returns your 10 latest emails.

Available Tools

• search_emails
  • Description: Search Gmail emails using a query.
  • Parameters:
    • query (required): Gmail search query (using Gmail's standard search syntax).
    • max_results (optional): Maximum number of results to return (default: 10).

Example search:

Can you show me any emails from sanrio in the past two days?

🔧 Technical Details

Security

This server requires authentication with Gmail via OAuth2:

• You will be prompted in your browser to authorize access on the first use.
• Credentials are stored locally in the specified token file.
• You can revoke authorization at any time through your Google account settings.
• It only requests read permissions for Gmail (no write permissions).

Environment Variables

• GMAIL_CREDENTIALS_FILE (required): Path to the Google OAuth credentials file.
• GMAIL_TOKEN_FILE (required): Path to the location where the token is saved.

To test, you can directly run the server:

GMAIL_CREDENTIALS_FILE="/path/to/credentials.json" \
GMAIL_TOKEN_FILE="/path/to/token.json" \
python -m gmail_mcp_server.server

Development

This server uses the Model Context Protocol to provide the following features:

• Resource access to get the latest emails.
• Support for email search tools.
• Permission management and logging.
• An extensible event handling mechanism.

🤝 Contribution Guidelines

If you wish to contribute to the project, please follow these guidelines:

1. Create a branch for your new feature or fix.
2. Commit your changes and add appropriate commit messages explaining the modifications.
3. Submit a pull request to the main repository and reference the relevant issue in the issue tracking system.

Please ensure that your code adheres to the project's coding standards and passes the existing test suite.