# Gmail MCP [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/A1-x-Tech/mcp-google-gmail  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1001  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/gmail-mcp

## Description
MCP server for the Gmail API: search, read and send email, manage drafts, labels and the trash.

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

```json
"mcpServers": {
  "gmail-mcp": {
    "command": "npx",
    "args": ["-y","mcp-google-gmail@latest"],
    "env": {
      "GOOGLE_GMAIL_CLIENT_ID": "",
      "GOOGLE_GMAIL_CLIENT_SECRET": "",
      "GOOGLE_GMAIL_REFRESH_TOKEN": ""
    }
  }
}
```

**Requires environment variables:** `GOOGLE_GMAIL_CLIENT_ID`, `GOOGLE_GMAIL_CLIENT_SECRET`, `GOOGLE_GMAIL_REFRESH_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What Gmail MCP does

Gmail MCP exposes Gmail mailbox operations through the Model Context Protocol. It supports searching and reading messages and threads, inspecting drafts and labels, viewing the mailbox profile, sending messages, and managing mailbox organization. The server includes 24 tools covering common Gmail workflows.

Email composition can follow a reviewable draft process: create a draft, inspect it, update it if needed, and send it as a separate action. Direct sending is also available through `send_message`. Draft updates replace the complete draft because Gmail does not provide partial draft editing.

Mailbox cleanup uses Gmail’s trash rather than permanent message deletion. Messages and threads can be trashed or restored for roughly 30 days. Draft deletion and label deletion are permanent operations, and sending cannot be undone.

## How it works

The server communicates with Gmail using the Gmail API and the Google account that authorized its token. Authentication can begin from the conversation when the user asks to connect Gmail. The flow guides OAuth client setup, receives Google’s redirect on `127.0.0.1`, uses PKCE, and stores the tokens without requiring a configuration file or server restart.

Read operations include Gmail query syntax and return mailbox information such as senders, subjects, dates, snippets, and message content. Decoded bodies are limited to a configurable size and include indicators when truncation occurs. Attachments are returned as metadata; retrieving attachment content requires the `raw_request` tool.

The client can distinguish read, write, and destructive operations and decide when to request confirmation. After an ambiguous send failure, the server does not retry automatically. Searching `in:sent` before retrying helps avoid sending the same email twice.

## Setup and configuration

Node.js 20 or newer and a Google account are required. Install the package as an MCP stdio server with:

```bash
npx -y mcp-google-gmail@latest
```

Codex, Claude Code, Claude Desktop, Cursor, and VS Code configurations are documented with this command. Claude Desktop uses its local JSON configuration on builds that support local MCP configuration; the package does not include a `.mcpb` extension bundle.

Authentication values can be supplied with `GOOGLE_GMAIL_CLIENT_ID`, `GOOGLE_GMAIL_CLIENT_SECRET`, and `GOOGLE_GMAIL_REFRESH_TOKEN`. Alternatively, the conversation-led connection flow handles OAuth setup after the server is added to the client.

The server requests the `gmail.modify` Google scope. That scope supports mailbox changes while excluding Gmail settings access and permanent message deletion.

## Tools and capabilities

- Search messages with Gmail query syntax and read messages or threads.
- Create, inspect, update, send, and permanently delete drafts.
- Send email directly, including recipient and CC workflows.
- Create, rename, apply, and remove labels.
- Change read, starred, archived, and label state.
- Move messages or threads to and from the trash.
- Make deliberate raw Gmail API requests through `raw_request`.

## Limitations and notes

All operations apply to one mailbox: the account associated with the authorized token. Sending email is irreversible, and the server does not claim that a sent message can be recalled. Trashing is reversible for about 30 days, but deleting a draft or label bypasses the trash. Message bodies are bounded by a configurable limit, and attachment data is not included directly in normal results.

Raw API requests can perform operations without a dedicated tool and may be destructive. The AI client, rather than the server alone, controls confirmation prompts. When a send times out or returns a 5xx error, verify the Sent folder before attempting another send.

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