@supercorp/gmail-mcp is a Gmail MCP server.

Installation & Usage

Run via npx using only the required flags:

npx @supercorp/gmail-mcp \
  --googleClientId <string> \
  --googleClientSecret <string> \
  --googleRedirectUri <string>

All other options can be adjusted in the table below.

CLI Arguments

| Flag | Type | Default | Description | |---------------------------|--------------------------|--------------------|-----------------------------------------------------------------------------------------------------------------------| | --googleClientId | string (required) | N/A | Your Google OAuth client ID. | | --googleClientSecret | string (required) | N/A | Your Google OAuth client secret. | | --googleRedirectUri | string (required) | N/A | OAuth 2.0 redirect URI registered in Google Cloud Console. | | --port | number | 8000 | TCP port for HTTP/SSE mode. | | --transport | sse or stdio | sse | MCP transport:• sse: HTTP server + Server-Sent Events• stdio: JSON-RPC over stdin/stdout | | --storage | see below | memory-single | Persistence backend for OAuth tokens:• memory-single: in-memory single-user (no header key)• memory: multi-user in-memory• upstash-redis-rest: durable via Upstash Redis REST API | | --storageHeaderKey | string (conditional) | none | HTTP header name (or Redis key prefix) to identify users when using memory or upstash-redis-rest. | | --upstashRedisRestUrl | string (conditional) | none | Upstash Redis REST URL (required if --storage=upstash-redis-rest). | | --upstashRedisRestToken | string (conditional) | none | Upstash Redis REST token (required if --storage=upstash-redis-rest). | | --sendOnly | boolean | false | If set, only the gmail.send tool is exposed (no read/draft capabilities). | | --googleState | string (optional) | none | Optional OAuth state parameter forwarded to Google. |

Storage Backends

• memory-single: in-memory single-user (quick demos; data lost on restart)
• memory: in-memory multi-user (requires --storageHeaderKey)
• upstash-redis-rest: persistent via Upstash Redis REST (requires --storageHeaderKey, --upstashRedisRestUrl, --upstashRedisRestToken)

Transports

• stdio JSON-RPC over stdin/stdout.
• sse HTTP server + Server-Sent Events:
  • Subscribe: GET http://localhost:<port>/
  • Send: POST http://localhost:<port>/message?sessionId=<session-id>

Exposed MCP Methods

| Tool | Description | |----------------------|---------------------------------------------------------------------------------------------------------------------| | auth_url | Returns a Gmail OAuth consent URL. | | exchange_auth_code | Exchanges the OAuth code for a refresh token and stores it. | | list_emails | Lists Gmail messages (maxResults, labelIds, query, pageToken, unreadOnly). | | read_email | Retrieves a full message by ID, converts HTML bodies into Markdown. | | list_drafts | Lists Gmail drafts (maxResults, query). | | read_draft | Reads a single draft by ID (in full). | | draft_email | Creates a new draft (sender, to, cc?, bcc?, subject, body, isHtml?). | | update_draft | Updates an existing draft by ID. | | delete_draft | Deletes a draft by ID. | | send_email | Sends an email (new or via an existing draft if draftId is provided). In send-only mode, this is the only tool. |