Gmail MCP Server

How to use

Use Claude Desktop with MCP support to access Gmail and calendar-aware capabilities. Open Claude Desktop and connect to the Gmail MCP server you configured. You can ask for an overview of your inbox, perform advanced searches across your email history, draft context-aware replies, and create calendar events based on information found in emails.

How to install

Prerequisites include Python 3.10+ and Google APIs enabled for Gmail and, optionally, Google Calendar. You also need OAuth 2.0 credentials for Gmail (and Calendar) and Claude Desktop with MCP support.

Installing via Smithery lets you set up the Gmail MCP server for Claude Desktop automatically.

npx -y @smithery/cli install @bastienchabal/gmail-mcp --client claude

If you prefer to install manually, follow these steps to set up a Python virtual environment and install dependencies.

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

# Create and activate a Python virtual environment using uv
pip install uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package in editable mode
uv pip install -e .

Configuration

Authenticate with Google and configure Claude Desktop to connect to the MCP server. You will set OAuth credentials and environment variables in Claude Desktop so sensitive data stays secure.

Example Claude Desktop configuration including the MCP server connection:

{
  "mcpServers": {
    "gmail-mcp": {
      "command": "/<absolute-path>/gmail-mcp/.venv/bin/mcp",
      "args": [
        "run",
        "/<absolute-path>/gmail-mcp/gmail_mcp/main.py:mcp"
      ],
      "cwd": "/<absolute-path>/gmail-mcp",
      "env": {
        "PYTHONPATH": "/<absolute-path>/gmail-mcp",
        "CONFIG_FILE_PATH": "/<absolute-path>/gmail-mcp/config.yaml",
        "GOOGLE_CLIENT_ID": "<your-client-id>",
        "GOOGLE_CLIENT_SECRET": "<your-client-secret>",
        "TOKEN_ENCRYPTION_KEY": "<generate-a-random-key>"
      }
    }
  }
}

Usage notes and troubleshooting

If Claude Desktop does not automatically connect to the MCP server, try restarting Claude Desktop, asking Claude to use the Gmail MCP server, or signing in to Gmail manually to grant permissions.

Authentication tips and calendar integration notes help resolve common issues, including ensuring the Calendar API is enabled and re-authenticating to grant Calendar scopes if needed.

Example requests

You can ask Claude to perform practical actions like: show me an overview of my inbox, find unread emails from a specific contact, draft a reply using full thread context, or create a calendar event from an email.

Available resources

The MCP provides rich contextual resources such as email context, thread context, sender context, authentication status, Gmail status, and server information to enable informed, context-aware interactions.

Security and beta notes

This MCP is in beta and designed to confirm sensitive actions with you before proceeding, such as sending emails or creating calendar events.

Email Context

Provides detailed information about specific emails and their threads to inform actions and responses.

Thread Context

Includes full conversation history for email threads to enable context-aware drafting and analysis.

Sender Context

Gathers sender-related history and relationships to tailor replies and understanding.

Authentication Status

Shows current Google authentication state and token validity.

Gmail Status

Overview of Gmail account status, including access and scopes granted.

Server Information

Details about the MCP server configuration and runtime environment.

Event Creation

Create calendar events from email content with natural language time descriptions.

Smart Scheduling

Suggests meeting times and contexts based on email threads.