Ajbr0wn Gmail MCP Server

🚀 Gmail MCP Server

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

✨ Features

• View the latest emails in your Gmail inbox.
• Search for emails using Gmail's search syntax.
• Secure authentication with the Gmail API based on 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 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 try to access Gmail through Claude, you'll be prompted in your browser to authorize the application. After authorization, your 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 for Gmail emails.
  • Parameters:
    • query (required): Gmail search query (using Gmail's standard search syntax).
    • max_results (optional): The maximum number of results to return (default: 10).

Example search:

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

🔧 Technical Details

Security

This server requires OAuth2 authentication with Gmail:

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

Environment Variables

• GMAIL_CREDENTIALS_FILE (required): The path to the Google OAuth credentials file.
• GMAIL_TOKEN_FILE (required): The location to save the token.

To test, you can run the server directly:

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:

• Resource access to recent emails.
• Support for email search tools.
• A secure authentication process.
• Automatic token refresh.

Logging

The server logs detailed operation information to stderr, including:

• Server startup information.
• Authentication status.
• Resource and tool usage.
• Any errors or issues.

🤝 Contribution

Pull requests are welcome! Please ensure:

• Documentation for new features is updated.
• Appropriate error handling is added.
• New OAuth processes are tested.
• The existing code style is followed.