home / mcp / gmail mcp server

Gmail MCP Server

Provides Gmail-based MCP operations, including sending emails via an OAuth-enabled Gmail API integration.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "heuristech-gmail-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/:your.path.to/gmail-mcp-server/server.py",
        "run",
        "server.py"
      ],
      "env": {
        "CLIENT_ID": "google.auth.app.client.id",
        "CLIENT_SECRET": "google.auth.app.client.secret",
        "REFRESH_TOKEN": "google.auth.app.refresh.token"
      }
    }
  }
}

You can manage Gmail operations with this MCP server, focused on sending emails and integrating Gmail actions into your MCP client workflows. It exposes a simple, reusable capability to send messages via an MCP endpoint and handles the authentication flow needed to access Gmail programmatically.

How to use

Install and run the MCP server, then connect to it from your MCP client. Use the provided send_mail capability to compose and dispatch emails through Gmail. You can configure OAuth credentials once and reuse them across requests. When your client triggers send_mail, the server will contact Gmail on your behalf and deliver the message to the intended recipient.

How to install

Prerequisites you need to prepare before installing the MCP server are listed here:

Python 3.12+
uv - Fast Python package installer and resolver
Google Cloud Console setup for Gmail API and OAuth

Set up Google Cloud credentials and obtain a credentials.json file, then place it at the project root as credentials.json. This file provides the Client ID and Client Secret used during OAuth.

Follow these concrete steps to install and configure the server locally:

# 1) Clone the project
git clone https://github.com/heuristech/gmail-mcp-server.git
cd gmail-mcp-server

# 2) Create and activate a virtual environment
uv venv
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

# 3) Install dependencies
uv sync

# 4) Obtain a refresh token via the local OAuth flow (recommended)
python get_refresh_token.py

Additional instructions and configuration

Create a local environment file to supply the Gmail API credentials and tokens. Copy the example environment file and fill in your values:

copy example.env .env

OAuth and tokens

Running the refresh token flow starts a small local server and opens a browser window to complete Google OAuth. After successful authentication, you will obtain a refresh token and client credentials, which are saved for subsequent server runs.

Claude Desktop Integration

When you are ready, install the server in Claude Desktop to integrate Gmail actions into Claude workflows.

MCP server configuration

The MCP server is configured to run with the runtime tool and a local server script. The following configuration snippet shows how to start the server and pass the required environment variables.

{
  "mcpServers": {
    "gmail-mcp-server": {
      "command": "uv",
      "args": [
          "--directory",
          "/:your.path.to/gmail-mcp-server/server.py",
          "run",
          "server.py"
      ],
      "env": {
        "CLIENT_ID": "google.auth.app.client.id",
        "CLIENT_SECRET": "google.auth.app.client.secret",
        "REFRESH_TOKEN": "google.auth.app.refresh.token"
      }   
    }   
  }
}

Available tools

send_mail

Sends a new email via Gmail using the Gmail MCP Server