ai.smithery/sebastianall1977-gmail-mcp

Install

Config snippet generator goes here (5 client tabs)

README

<div align="center">
    <h1 align="center">Gmail MCP Server</h1>
    <p align=center>
        <a href="https://badge.fury.io/js/@shinzolabs%2Fgmail-mcp"><img src="https://badge.fury.io/js/@shinzolabs%2Fgmail-mcp.svg" alt="NPM Version"></a>
        <a href="https://github.com/shinzo-labs/gmail-mcp/stargazers"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.github.com%2Frepos%2Fshinzo-labs%2Fgmail-mcp%2Fstargazers&query=%24.length&logo=github&label=stars&color=e3b341" alt="Stars"></a>
        <a href="https://github.com/shinzo-labs/gmail-mcp/forks"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.github.com%2Frepos%2Fshinzo-labs%2Fgmail-mcp%2Fforks&query=%24.length&logo=github&label=forks&color=8957e5" alt="Forks"></a>
        <a href="https://smithery.ai/server/@shinzo-labs/gmail-mcp"><img src="https://smithery.ai/badge/@shinzo-labs/gmail-mcp" alt="Smithery Calls"></a>
        <a href="https://www.npmjs.com/package/@shinzolabs/gmail-mcp"><img src="https://img.shields.io/npm/dm/%40shinzolabs%2Fgmail-mcp" alt="NPM Downloads"></a>
</div>

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server implementation for the [Gmail](https://developers.google.com/gmail/api) API, providing a standardized interface for email management, sending, and retrieval.

<p align="center"><img height="512" src=https://github.com/user-attachments/assets/b61db02e-bde4-4386-b5a9-2b1c6a989925></p>

## Features

- Complete Gmail API coverage including messages, threads, labels, drafts, and settings
- Support for sending, drafting, and managing emails
- Label management with customizable colors and visibility settings
- Thread operations for conversation management
- Settings management including vacation responder, IMAP/POP, and language settings
- History tracking for mailbox changes
- Secure OAuth2 authentication using Google Cloud credentials

## Prerequisites

### Dependencies

For simplest installation, install [Node.js 18+](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). If you would like to build locally, you will also need to install [pnpm](https://pnpm.io/installation).

### Google Workspace Setup

To run this MCP server, you will need to set up a Google API Client for your organization, with each user running a script to retrieve their own OAuth refresh token.

#### Google API Client Setup (once per organization)

1. Go to the [Google Cloud Console](https://console.cloud.google.com).
2. Create a new project or select an existing one.
3. Enable the Gmail API for your project.
4. Go to Credentials and create an OAuth 2.0 Client ID. Choose "Desktop app" for the client type.
5. Download and save the OAuth keys JSON as `~/.gmail-mcp/gcp-oauth.keys.json`. ⚠️ NOTE: to create `~/.gmail-mcp/` through MacOS's Finder app you need to [enable hidden files](https://stackoverflow.com/questions/5891365/mac-os-x-doesnt-allow-to-name-files-starting-with-a-dot-how-do-i-name-the-hta) first.
6. (Optional) For remote server installation (ex. using Smithery CLI), note the `CLIENT_ID` and `CLIENT_SECRET` from this file.

#### Client OAuth (once per user)

1. Have the user copy `~/.gmail-mcp/gcp-oauth.keys.json` to their computer at the same path.
2. Run `npx @shinzolabs/gmail-mcp auth`.
3. A browser window will open where the user may select a profile, review the requested scopes, and approve.
4. (Optional) For remote server installation, note the file path mentioned in the success message (`~/.gmail-mcp/credentials.json` by default). The user's `REFRESH_TOKEN` will be found here.

## Client Configuration

There are several options to configure your MCP client with the server. For hosted/remote server setup, use Smithery's CLI with a [Smithery API Key](https://smithery.ai/docs/registry#registry-api). For local installation, use `npx` or build from source. Each of these options is explained below.

### Smithery Remote Server (Recommended)

To add a remote server to your MCP client `config.json`, run the following command from [Smithery CLI](https://github.com/smithery-ai/cli?tab=readme-ov-file#smithery-cli--):

```bash
npx -y @smithery/cli install @shinzo-labs/gmail-mcp
```

Enter your `CLIENT_ID`, `CLIENT_SECRET`, and `REFRESH_TOKEN` when prompted.

### Smithery SDK

If you are developing your own agent application, you can use the boilerplate code [here](https://smithery.ai/server/@shinzo-labs/gmail-mcp/api).

### NPX Local Install

To install the server locally with `npx`, add the following to your MCP client `config.json`:
```javascript
{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@shinzolabs/gmail-mcp"
      ]
    }
  }
}
```

### Build from Source

1. Download the repo:
```bash
git clone https://github.com/shinzo-labs/gmail-mcp.git
```

2. Install packages and build with `pnpm` (inside cloned repo):
```bash
pnpm i && pnpm build
```

3. Add the following to your MCP client `config.json`:
```javascript
{
  "mc