gmail

This MCP server provides Gmail integration for MCP clients like Claude Desktop. It exposes an API to view your Gmail data and perform searches using Gmail's built-in query syntax. The server authenticates via OAuth2, storing tokens locally to enable seamless re-use across sessions. Tools available include a resource that lets you fetch recent emails and a search tool that lets you query emails using Gmail's search operators. To use it, configure Claude Desktop to point at the Gmail MCP server and ensure you have supplied the credentials and token file paths. When prompted to authorize access in your browser, complete the OAuth flow to grant read-only access to Gmail.

Once configured, you can request recent emails with the available resource, or call the search tool to filter messages by sender, date, subject, or content using Gmail's syntax. If you need to refresh tokens, the server handles automatic refresh as long as the token file remains accessible.

Prerequisites:

• An active Python environment (3.8+ recommended) or conda
• Internet access to install dependencies

Installation steps:

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

# 2) Install the MCP Gmail server package in editable mode
# (Assumes you have the repository checked out as gmail-mcp-server)
cd gmail-mcp-server
pip install -e .

Configuration steps (per Claude Desktop integration):

// Claud Desktop config snippet (example)
{
  "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"
      }
    }
  }
}

Run the server directly (testing):

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

Note: Replace all /path/to/ placeholders with actual paths. You will need to obtain Gmail OAuth credentials and store them at the specified credentials file path, then authorize the application in your browser to create the token file locally.

Tips and common issues:

• Ensure the credentials.json is downloaded from Google Cloud Console and placed at the path specified by GMAIL_CREDENTIALS_FILE.
• The first run will prompt you to authorize access via a browser; the resulting token.json will be created at the location specified by GMAIL_TOKEN_FILE.
• If the token expires, the server will refresh it automatically, provided the token file remains writable.
• The available resources and tools expose only read access to Gmail data for security purposes.
• When debugging, run with environment variables set as shown in the example to mimic Claude Desktop integration.
• If you change the PYTHONPATH or module layout, update the env PYTHONPATH accordingly so imports resolve correctly.