# faithk7-gmail-mcp [Health: Active]

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

## Description
Manage Gmail messages, threads, labels, drafts, and settings from your workflows. Send and organiz…

## Tools
Capabilities this server exposes over MCP:

- **create_draft** — Create a draft email in Gmail. Note the mechanics of the raw parameter.
- **delete_draft** — Delete a draft
- **get_draft** — Get a specific draft by ID
- **list_drafts** — List drafts in the user's mailbox
- **send_draft** — Send an existing draft
- **create_label** — Create a new label
- **delete_label** — Delete a label
- **get_label** — Get a specific label by ID
- **list_labels** — List all labels in the user's mailbox
- **patch_label** — Patch an existing label (partial update)
- **update_label** — Update an existing label
- **batch_delete_messages** — Delete multiple messages
- **batch_modify_messages** — Modify the labels on multiple messages
- **delete_message** — Immediately and permanently delete a message
- **get_message** — Get a specific message by ID with format options
- **list_messages** — List messages in the user's mailbox with optional filtering
- **modify_message** — Modify the labels on a message
- **send_message** — Send an email message to specified recipients. Note the mechanics of the raw parameter.
- **trash_message** — Move a message to the trash
- **untrash_message** — Remove a message from the trash
- **get_attachment** — Get a message attachment
- **delete_thread** — Delete a thread
- **get_thread** — Get a specific thread by ID
- **list_threads** — List threads in the user's mailbox
- **modify_thread** — Modify the labels applied to a thread
- **trash_thread** — Move a thread to the trash
- **untrash_thread** — Remove a thread from the trash
- **get_auto_forwarding** — Gets auto-forwarding settings
- **get_imap** — Gets IMAP settings
- **get_language** — Gets language settings
- **get_pop** — Gets POP settings
- **get_vacation** — Get vacation responder settings
- **update_auto_forwarding** — Updates automatic forwarding settings
- **update_imap** — Updates IMAP settings
- **update_language** — Updates language settings
- **update_pop** — Updates POP settings
- **update_vacation** — Update vacation responder settings
- **add_delegate** — Adds a delegate to the specified account
- **remove_delegate** — Removes the specified delegate
- **get_delegate** — Gets the specified delegate
- **list_delegates** — Lists the delegates for the specified account
- **create_filter** — Creates a filter
- **delete_filter** — Deletes a filter
- **get_filter** — Gets a filter
- **list_filters** — Lists the message filters of a Gmail user
- **create_forwarding_address** — Creates a forwarding address
- **delete_forwarding_address** — Deletes the specified forwarding address
- **get_forwarding_address** — Gets the specified forwarding address
- **list_forwarding_addresses** — Lists the forwarding addresses for the specified account
- **create_send_as** — Creates a custom send-as alias
- **delete_send_as** — Deletes the specified send-as alias
- **get_send_as** — Gets the specified send-as alias
- **list_send_as** — Lists the send-as aliases for the specified account
- **patch_send_as** — Patches the specified send-as alias
- **update_send_as** — Updates a send-as alias
- **verify_send_as** — Sends a verification email to the specified send-as alias
- **delete_smime_info** — Deletes the specified S/MIME config for the specified send-as alias
- **get_smime_info** — Gets the specified S/MIME config for the specified send-as alias
- **insert_smime_info** — Insert (upload) the given S/MIME config for the specified send-as alias
- **list_smime_info** — Lists S/MIME configs for the specified send-as alias
- **set_default_smime_info** — Sets the default S/MIME config for the specified send-as alias
- **get_profile** — Get the current user's Gmail profile
- **watch_mailbox** — Watch for changes to the user's mailbox
- **stop_mail_watch** — Stop receiving push notifications for the given user mailbox

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

```json
"mcpServers": {
  "faithk7-gmail-mcp": {
    "command": "npx",
    "args": ["-y","@shinzolabs/gmail-mcp"],
    "env": {
      "CLIENT_ID": "",
      "CLIENT_SECRET": "",
      "REFRESH_TOKEN": ""
    }
  }
}
```

**Requires environment variables:** `CLIENT_ID`, `CLIENT_SECRET`, `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 faithk7-gmail-mcp MCP server does

faithk7-gmail-mcp MCP server connects an MCP-compatible client to the Gmail API. Its tools cover mailbox inspection and message operations, including listing and retrieving messages, reading attachments, changing labels, sending mail, moving messages to or from trash, and permanently deleting messages. Batch operations are available for modifying or deleting multiple messages.

The server also exposes Gmail threads, labels, drafts, and selected account settings. Agents can create, update, send, and remove drafts; create and edit labels; and manage thread labels or deletion state. Settings tools cover auto-forwarding, IMAP, POP, vacation responder, and language preferences. Mailbox watch tools can start or stop push notifications for changes, while the history capability supports tracking mailbox changes.

## How it works

Authentication uses OAuth2 credentials created in Google Cloud. An administrator or developer enables the Gmail API, creates a Desktop OAuth client, and saves the client keys in the server’s configuration directory. Each user then runs the authentication command and approves the requested scopes in a browser. The resulting credentials include a refresh token used for later access.

faithk7-gmail-mcp MCP server can communicate with an MCP client through a local npx process or a Node.js process built from source. The documentation also describes remote installation through the Smithery CLI and a Streamable HTTP transport. Remote connections require the Google client ID, client secret, and user refresh token as configuration values.

## Setup and configuration

Node.js 18 or newer is the simplest local prerequisite. Building from source additionally requires pnpm. For local OAuth setup, place the Google client file at `~/.gmail-mcp/gcp-oauth.keys.json`, then run:

```bash
npx @shinzolabs/gmail-mcp auth
```

A local MCP client can launch the package with `npx @shinzolabs/gmail-mcp`. Alternatively, clone the project, install dependencies, build it with pnpm, and point the client at `dist/index.js`.

The default configuration directory is `~/.gmail-mcp`. `MCP_CONFIG_DIR`, `GMAIL_OAUTH_PATH`, and `GMAIL_CREDENTIALS_PATH` can change where OAuth and user credential files are stored. `AUTH_SERVER_PORT` controls the temporary authentication server, while `PORT` controls Streamable HTTP. Telemetry is enabled by default and can be changed with `TELEMETRY_ENABLED`.

## Tools and capabilities

Available tool groups include:

- Messages: list, retrieve, send, modify, trash, restore, delete, and batch-process messages; retrieve attachments.
- Threads: list, retrieve, relabel, trash, restore, and delete threads.
- Labels: list, retrieve, create, update, partially update, and delete labels.
- Drafts: list, retrieve, create, replace, delete, and send drafts.
- Settings: read and update forwarding, IMAP, POP, vacation responder, and language settings.
- User and mailbox state: retrieve the profile, configure or stop mailbox watches, and access history-related mailbox changes.

## Limitations and notes

Gmail API access must be enabled in a Google Cloud project, and users must approve OAuth access before the server can operate on their mail. Remote deployment needs credentials supplied separately from the local file-based flow. The material does not identify client-specific features or permissions beyond support for MCP client configuration, local execution, Smithery installation, and Streamable HTTP transport.

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