# Gmail MCP server

> Lets an AI client read, search, organize, draft, and send Gmail messages and conversations.

- Repository: https://github.com/pulsemcp/mcp-servers
- Page: https://hostedmcp.org/servers/pulsemcp/gmail
- Official: yes
- Transport: stdio
- Stars: 81
- License: MIT
- Latest version: 0.4.12

## Install

### Claude Code

```sh
claude mcp add --env GMAIL_OAUTH_CLIENT_ID=<YOUR_GMAIL_OAUTH_CLIENT_ID> --env GMAIL_OAUTH_CLIENT_SECRET=<YOUR_GMAIL_OAUTH_CLIENT_SECRET> --env GMAIL_OAUTH_REFRESH_TOKEN=<YOUR_GMAIL_OAUTH_REFRESH_TOKEN> --env GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY=<YOUR_GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY> gmail -- npx -y gmail-workspace-mcp-server
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "-y",
        "gmail-workspace-mcp-server"
      ],
      "env": {
        "GMAIL_OAUTH_CLIENT_ID": "<YOUR_GMAIL_OAUTH_CLIENT_ID>",
        "GMAIL_OAUTH_CLIENT_SECRET": "<YOUR_GMAIL_OAUTH_CLIENT_SECRET>",
        "GMAIL_OAUTH_REFRESH_TOKEN": "<YOUR_GMAIL_OAUTH_REFRESH_TOKEN>",
        "GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "<YOUR_GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "gmail": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "gmail-workspace-mcp-server"
      ],
      "env": {
        "GMAIL_OAUTH_CLIENT_ID": "<YOUR_GMAIL_OAUTH_CLIENT_ID>",
        "GMAIL_OAUTH_CLIENT_SECRET": "<YOUR_GMAIL_OAUTH_CLIENT_SECRET>",
        "GMAIL_OAUTH_REFRESH_TOKEN": "<YOUR_GMAIL_OAUTH_REFRESH_TOKEN>",
        "GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "<YOUR_GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY>"
      }
    }
  }
}
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "-y",
        "gmail-workspace-mcp-server"
      ],
      "env": {
        "GMAIL_OAUTH_CLIENT_ID": "<YOUR_GMAIL_OAUTH_CLIENT_ID>",
        "GMAIL_OAUTH_CLIENT_SECRET": "<YOUR_GMAIL_OAUTH_CLIENT_SECRET>",
        "GMAIL_OAUTH_REFRESH_TOKEN": "<YOUR_GMAIL_OAUTH_REFRESH_TOKEN>",
        "GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "<YOUR_GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY>"
      }
    }
  }
}
```

### Codex (`~/.codex/config.toml`)

```toml
[mcp_servers.gmail]
command = "npx"
args = ["-y", "gmail-workspace-mcp-server"]

[mcp_servers.gmail.env]
GMAIL_OAUTH_CLIENT_ID = "<YOUR_GMAIL_OAUTH_CLIENT_ID>"
GMAIL_OAUTH_CLIENT_SECRET = "<YOUR_GMAIL_OAUTH_CLIENT_SECRET>"
GMAIL_OAUTH_REFRESH_TOKEN = "<YOUR_GMAIL_OAUTH_REFRESH_TOKEN>"
GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY = "<YOUR_GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY>"
```

### Gemini CLI (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "-y",
        "gmail-workspace-mcp-server"
      ],
      "env": {
        "GMAIL_OAUTH_CLIENT_ID": "<YOUR_GMAIL_OAUTH_CLIENT_ID>",
        "GMAIL_OAUTH_CLIENT_SECRET": "<YOUR_GMAIL_OAUTH_CLIENT_SECRET>",
        "GMAIL_OAUTH_REFRESH_TOKEN": "<YOUR_GMAIL_OAUTH_REFRESH_TOKEN>",
        "GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "<YOUR_GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `GMAIL_OAUTH_CLIENT_ID` | no | yes | OAuth2 client ID from Google Cloud Console (for personal Gmail accounts). |
| `GMAIL_OAUTH_CLIENT_SECRET` | no | yes | OAuth2 client secret from Google Cloud Console. |
| `GMAIL_OAUTH_REFRESH_TOKEN` | no | yes | Refresh token from the OAuth2 setup script. |
| `GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY` | no | yes | Service account private key in PEM format (for Google Workspace). |
| `GMAIL_ENABLED_TOOLGROUPS` | no | no | Comma-separated list of tool groups to enable (readonly, readwrite, readwrite_external). |
| `GMAIL_IMPERSONATE_EMAIL` | no | no | Email address to impersonate (required for service account mode). |
| `GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL` | no | no | Service account email address (for Google Workspace). |

## Tools (22)

- `readonly`
- `readwrite`
- `readwrite_external`
- `count`
- `labels`
- `sort_by`
- `after`
- `before`
- `email_id`
- `query`
- `status`
- `is_starred`
- `remove_labels`
- `thread_id`
- `draft_id`
- `delete`
- `subject`
- `plaintext_body`
- `html_body`
- `bcc`
- `reply_to_email_id`
- `from_draft_id`

## FAQ

### How does the Gmail MCP server authenticate?

It supports OAuth2 for personal Gmail accounts and a service account with domain-wide delegation for Google Workspace accounts.

### Can the Gmail MCP server search my inbox?

Yes, it searches emails using Gmail's query syntax, such as from:user@example.com or is:unread.

### Can I limit the Gmail MCP server to read-only access?

Yes, set the GMAIL_ENABLED_TOOLGROUPS environment variable to readonly to disable write and send tools.

### Can the Gmail MCP server send emails?

Yes, the send_email tool sends new emails or replies, either directly or from an existing draft.

### How do I get an OAuth2 refresh token for Gmail?

Run the built-in oauth-setup command with your client ID and secret, then sign in through the browser.