# Gmail [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/mcp-z/mcp-gmail#readme  
**GitHub Stars:** 5  
**npm Downloads (last month):** 747  
**Views:** 5  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/gmail-3

## Description
Gmail integration with OAuth authentication, message search, batch operations, and Sheets export

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "gmail": {
    "command": "npx",
    "args": ["-y","@mcp-z/cli"],
    "env": {
      "GOOGLE_CLIENT_ID": "",
      "GOOGLE_CLIENT_SECRET": "",
      "AUTH_MODE": "",
      "GOOGLE_SERVICE_ACCOUNT_KEY_FILE": "",
      "REDIRECT_URI": "",
      "TOKEN_STORE_URI": "",
      "DCR_STORE_URI": ""
    }
  }
}
```

**Requires environment variables:** `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `AUTH_MODE`, `GOOGLE_SERVICE_ACCOUNT_KEY_FILE`, `REDIRECT_URI`, `TOKEN_STORE_URI`, `DCR_STORE_URI` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What the Gmail MCP server does

The Gmail MCP server exposes Gmail operations to MCP-compatible clients. Its tools cover message discovery, message retrieval, sending and replying, read-state changes, trashing, label management, and CSV export. It also provides an `email` resource and two prompts: `draft-email` and `query-syntax`.

Available tools include:

- `message-search` and `message-get` for finding and reading messages
- `message-send` and `message-respond` for outbound email
- `message-mark-read` and `message-move-to-trash` for message state changes
- `labels-list`, `label-add`, `label-delete`, and `categories-list` for mailbox organization
- `messages-export-csv` for exporting messages

The package is intended for Node.js 20 or newer. It can be started directly with `npx` and inspected or called through `@mcp-z/cli`.

## How it works

The Gmail MCP server supports both stdio and HTTP transports. Stdio is suitable for local client configurations, while HTTP can expose the MCP endpoint at a configured address such as `/mcp`. The server negotiates either of the two protocol revisions described in the project documentation, allowing a compatible client to select the revision it supports.

Authentication normally uses Google OAuth. A local setup uses a loopback redirect by default; hosted deployments can set a public callback with `REDIRECT_URI`. Service-account authentication is also available. Dynamic client registration is supported for HTTP deployments using DCR mode, which requires a public base URL.

OAuth tokens and DCR registrations use storage URIs handled through `keyv-registry`. File storage under `~/.mcp-z/` and in-memory storage work without an additional adapter. Other storage protocols require the corresponding adapter package.

## Setup and configuration

Create or select a Google Cloud project, enable the Gmail API, and create OAuth credentials. Use a Desktop app credential for stdio. For HTTP, use a Web application credential and register the callback URL. The documented OAuth scopes include OpenID, Google profile and email identity, and full Gmail access. Test users must be added to the Google Cloud consent configuration where required.

A minimal stdio configuration starts the Gmail MCP server with `npx`:

```json
{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["-y", "@mcp-z/mcp-gmail"]
    }
  }
}
```

Set `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` for loopback OAuth. Service-account mode uses `AUTH_MODE=service-account` and a path supplied through `GOOGLE_SERVICE_ACCOUNT_KEY_FILE`. HTTP deployments can pass a port and configure `REDIRECT_URI` when a public callback is needed.

## Limitations and notes

DCR mode is HTTP-only and requires a public base URL. In that mode, CSV export and the `/files` endpoint are disabled, and `resourceStoreUri` is ignored. Non-file and non-memory storage backends need an adapter installed alongside the package. The documented setup grants the `mail.google.com` scope, so administrators should review the access level appropriate for their deployment.

Use the client’s standard stdio or HTTP MCP configuration and complete the Google authorization flow before calling Gmail tools.

_Full upstream README: https://allmcps.com/mcp/gmail-3/readme_