# gmail

Hooks Gmail into an AI assistant: read threads, search, label, draft and send. Works for personal accounts and Google Workspace.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 81
- Author: pulsemcp
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/pulsemcp/mcp-servers/tree/HEAD/experimental/gmail
- Updated: 2026-10-09
- HTML: https://affpapa.org/en/nevibecode/mcp/gmail

## What it does

The server hands your agent a set of Gmail tools. It can pull conversation lists filtered by label, fetch a full message with attachment details, and run searches in Gmail query syntax. Labels, read/unread state, stars and archiving are all writable, and drafts or replies can be created and sent.

Auth comes in two flavours. A personal `@gmail.com` mailbox uses OAuth2: enable the Gmail API in a Google Cloud project, set up and publish the consent screen, then make Desktop app credentials. Grab the refresh token with `npx gmail-workspace-mcp-server oauth-setup <client_id> <client_secret>`; the server listens on port 3000 unless you override it with `PORT`. Workspace setups go through a service account with domain-wide delegation and the four Gmail scopes.

Permissions are split into tool groups picked with `GMAIL_ENABLED_TOOLGROUPS`: `readonly`, `readwrite`, and `readwrite_external`, which adds sending. All of them are on out of the box, so the agent can send mail on the first run. Skip publishing the consent screen and the refresh token lapses every 7 days.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `GMAIL_OAUTH_CLIENT_ID`, `GMAIL_OAUTH_CLIENT_SECRET`, `GMAIL_OAUTH_REFRESH_TOKEN`, `GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL`, `GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY`, `GMAIL_IMPERSONATE_EMAIL`, `GMAIL_ENABLED_TOOLGROUPS` — keys and tokens: ask the human for the values, never commit them or put them in shared files.
- Works with: Gmail

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env GMAIL_OAUTH_CLIENT_ID=<GMAIL_OAUTH_CLIENT_ID> --env GMAIL_OAUTH_CLIENT_SECRET=<GMAIL_OAUTH_CLIENT_SECRET> --env GMAIL_OAUTH_REFRESH_TOKEN=<GMAIL_OAUTH_REFRESH_TOKEN> --env GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL=<GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL> --env GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY=<GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY> --transport stdio gmail -- npx -y gmail-workspace-mcp-server
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
codex mcp add gmail --env GMAIL_OAUTH_CLIENT_ID=<GMAIL_OAUTH_CLIENT_ID> --env GMAIL_OAUTH_CLIENT_SECRET=<GMAIL_OAUTH_CLIENT_SECRET> --env GMAIL_OAUTH_REFRESH_TOKEN=<GMAIL_OAUTH_REFRESH_TOKEN> --env GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL=<GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL> --env GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY=<GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY> -- npx -y gmail-workspace-mcp-server
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "gmail": {
            "command": "npx",
            "args": [
                "-y",
                "gmail-workspace-mcp-server"
            ],
            "env": {
                "GMAIL_OAUTH_CLIENT_ID": "<GMAIL_OAUTH_CLIENT_ID>",
                "GMAIL_OAUTH_CLIENT_SECRET": "<GMAIL_OAUTH_CLIENT_SECRET>",
                "GMAIL_OAUTH_REFRESH_TOKEN": "<GMAIL_OAUTH_REFRESH_TOKEN>",
                "GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL": "<GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL>",
                "GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "<GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY>"
            }
        }
    }
}
```
Replace <…> with your own values. 2 more environment variables are in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "gmail": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "gmail-workspace-mcp-server"
            ],
            "env": {
                "GMAIL_OAUTH_CLIENT_ID": "<GMAIL_OAUTH_CLIENT_ID>",
                "GMAIL_OAUTH_CLIENT_SECRET": "<GMAIL_OAUTH_CLIENT_SECRET>",
                "GMAIL_OAUTH_REFRESH_TOKEN": "<GMAIL_OAUTH_REFRESH_TOKEN>",
                "GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL": "<GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL>",
                "GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "<GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY>"
            }
        }
    }
}
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e GMAIL_OAUTH_CLIENT_ID=<GMAIL_OAUTH_CLIENT_ID> -e GMAIL_OAUTH_CLIENT_SECRET=<GMAIL_OAUTH_CLIENT_SECRET> -e GMAIL_OAUTH_REFRESH_TOKEN=<GMAIL_OAUTH_REFRESH_TOKEN> -e GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL=<GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL> -e GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY=<GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY> gmail npx -y gmail-workspace-mcp-server
```
Replace <…> with your own values. 2 more environment variables are in the server README

## When to use it
- locate a message using Gmail search syntax
- read a thread and list its attachments
- prepare a reply draft from task context
- file incoming mail under the right labels
- lock an agent down to read-only mailbox access

## Example prompts
- Search Gmail for the thread with the contractor from March and show the latest message
- Draft a reply to that message and save it in Gmail
- Send an email to the address in `contacts.md` with the subject “Friday call”

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

From the same set: [pulsemcp/mcp-servers](https://affpapa.org/en/nevibecode/by/pulsemcp/mcp-servers.md) — 9 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md