Log inSubmit server
Faithk7 Gmail MCP logo

Faithk7 Gmail MCP

Connects AI workflows to Gmail for searching, sending, drafting, labeling, and managing messages, threads, and settings.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Faithk7 Gmail MCP

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "faithk7-gmail-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@shinzolabs/gmail-mcp"
      ],
      "env": {
        "CLIENT_ID": "YOUR_VALUE_HERE",
        "CLIENT_SECRET": "YOUR_VALUE_HERE",
        "REFRESH_TOKEN": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Automated check passed— started and listed 64 tools correctly (1mo ago).

Overview

faithk7-gmail-mcp MCP server exposes Gmail API operations through the Model Context Protocol. It supports messages, threads, labels, drafts, mailbox history, notifications, and account settings, with OAuth2 authentication through Google Cloud credentials. Use it when an MCP-compatible agent needs to read, organize, compose, send, or configure Gmail data. It can run locally with npx or from a built Node.js project, and it also supports remote Streamable HTTP deployment.

Use cases

  • Search and retrieve Gmail messages for an agent workflow
  • Compose, save, and send emails through Gmail
  • Organize messages and threads with labels
  • Manage drafts and mailbox settings
  • Monitor mailbox changes with Gmail watch tools

Key features

  • Gmail message and attachment operations
  • Thread, label, and draft management
  • Email sending and batch message actions
  • Forwarding, IMAP, POP, vacation, and language settings
  • OAuth2 authentication with Google Cloud credentials
  • Local npx and remote Streamable HTTP deployment

Tools64

What Faithk7 Gmail MCP lets your agent do. Expand a tool for its parameters.

Verified live~6.9k tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 3d ago

Recent health check succeeded.

21/21 checks healthy over the last 91d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 7d ago via OSV.dev · @shinzolabs/gmail-mcp (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

npm downloads3.1kPackage downloads in the last 30 days.
Last commit1y agoMost recent push to the default branch.
Availability100%Our rolling endpoint + install checks that succeeded.
Install checkPassedOur sandbox started it and listed its tools.
Tools exposed64Callable tools this server registers over MCP.
Directory activity2 viewsConfig copies, upvotes, and views on AllMCPs.

How Faithk7 Gmail MCP works

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:

Terminal
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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Faithk7 Gmail MCP

faithk7-gmail-mcp is an MCP server that connects AI agents to the Gmail API through OAuth2. Its main tools list, retrieve, modify, send, trash, and delete messages; manage threads, labels, and drafts; read or update Gmail settings; and watch mailbox changes. It supports local and remote MCP deployment.

Install it locally by adding an npx MCP configuration that runs `@shinzolabs/gmail-mcp`, or build from source with pnpm and launch `dist/index.js`. You can also install the remote version with the Smithery CLI. Node.js 18 or newer is required for the simplest local setup.

Authenticate by enabling the Gmail API, creating a Google Cloud Desktop OAuth client, saving its JSON file under `~/.gmail-mcp/gcp-oauth.keys.json`, and running `npx @shinzolabs/gmail-mcp auth`. The user then approves access in a browser, producing credentials and a refresh token.

The server uses `CLIENT_ID`, `CLIENT_SECRET`, and `REFRESH_TOKEN` for remote connections, plus optional variables for credential paths, ports, configuration storage, and telemetry. Local setups can use the default files under `~/.gmail-mcp` instead of supplying the remote OAuth values.

The documentation does not name Cursor or another specific MCP client. It provides generic MCP client configuration for local npx execution, a built Node.js process, Smithery remote installation, and Streamable HTTP, so compatibility depends on the client’s support for those MCP connection methods.

Related MCP servers

All in Communication All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewFaithk7 Gmail MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/faithk7-gmail-mcp?style=directory)](https://allmcps.com/mcp/faithk7-gmail-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/faithk7-gmail-mcp"><img src="https://allmcps.com/api/badge/faithk7-gmail-mcp?style=directory" alt="Faithk7 Gmail MCP on AllMCPs" /></a>