# Gmail MCP Server

<p align="center">
  <img src="https://img.shields.io/badge/Node.js-18+-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js" />
  <img src="https://img.shields.io/badge/MCP-Protocol-000000?style=for-the-badge&logo=anthropic&logoColor=white" alt="MCP" />
  <img src="https://img.shields.io/badge/Gmail_API-EA4335?style=for-the-badge&logo=gmail&logoColor=white" alt="Gmail API" />
  <img src="https://img.shields.io/badge/License-MIT-blue?style=for-the-badge" alt="License" />
</p>

<p align="center">
  <strong>A Model Context Protocol (MCP) server that lets AI assistants send, read, and manage Gmail — through natural language.</strong>
</p>

<p align="center">
  Built with Node.js · Compatible with Claude Desktop & other MCP clients
</p>

---

## Overview

Gmail MCP Server bridges AI assistants and Gmail. Instead of switching tabs or writing scripts, you ask your AI client to send an email, list unread messages, archive inbox clutter, or fill a reusable template — and the server handles the rest over stdio.

| Capability | How it works |
|---|---|
| **Send mail** | Gmail SMTP via Nodemailer + App Password |
| **Read & manage** | Gmail API v1 via OAuth2 refresh token |
| **Templates** | Mustache variables in local `.txt` files |
| **Transport** | MCP over stdio (no HTTP server required) |

---

## Features

- **Send custom emails** — plain text or HTML
- **Introduction emails** — one-shot professional outreach
- **Template engine** — Mustache-powered reusable email bodies
- **Inbox tools** — list labels, list unread (with Gmail search queries), fetch by ID
- **Mailbox actions** — archive (remove from Inbox) or move to trash
- **Config check** — verify SMTP credentials before sending
- **Secure by design** — secrets stay in `.env`; never committed to git

---

## Architecture

```text
  +------------------+          stdio / JSON-RPC         +---------------------+
  |  MCP Client      |  <------------------------------> |  Gmail MCP Server   |
  |  Claude Desktop  |                                   |  index.js           |
  |  Cursor, etc.    |                                   +----------+----------+
  +------------------+                                              |
                                       +----------------------------+----------------------------+
                                       |                            |                            |
                                       v                            v                            v
                               +---------------+            +---------------+            +---------------+
                               |  Nodemailer   |            |  Gmail API    |            |  Templates    |
                               |  SMTP send    |            |  OAuth2 read  |            |  Mustache     |
                               +---------------+            +---------------+            +---------------+
```

---

## Tech Stack

| Layer | Technology |
|---|---|
| Runtime | Node.js (ES Modules) |
| Protocol | [Model Context Protocol](https://modelcontextprotocol.io/) over stdio |
| MCP SDK | `@modelcontextprotocol/sdk` |
| Sending | `nodemailer` → Gmail SMTP |
| Reading / managing | `googleapis` → Gmail API v1 |
| Auth | Gmail App Password (send) · OAuth2 refresh token (read/manage) |
| Config | `dotenv` |
| Templating | `mustache` |

---

## Project Structure

```text
gmail-mcp-server/
├── index.js              # MCP server entry — tool registration & handlers
├── lib/
│   └── gmail.js          # OAuth2 client + Gmail API helpers
├── templates/
│   ├── introduction.txt  # Intro email template
│   └── follow_up.txt     # Follow-up email template
├── .env.example          # Environment variable template
├── package.json
└── README.md
```

---

## Available Tools

| Tool | Description | Auth |
|---|---|---|
| `send_email` | Send a custom email (text or HTML) | App Password |
| `send_introduction_email` | Send a professional introduction | App Password |
| `send_template_email` | Send from a Mustache template | App Password |
| `check_gmail_config` | Validate SMTP credentials | App Password |
| `list_email_templates` | List templates in `/templates` | None |
| `list_labels` | List Gmail labels | OAuth2 |
| `list_unread_emails` | List unread mail (optional query) | OAuth2 |
| `get_email` | Fetch a full message by ID | OAuth2 |
| `archive_email` | Remove a message from Inbox | OAuth2 |
| `delete_email` | Move a message to Trash | OAuth2 |
| `list_attachments` | List attachments on a message | OAuth2 |
| `download_attachment` | Download an attachment to disk | OAuth2 |

---

## Getting Started

### Prerequisites

- [Node.js](https://nodejs.org/) 18 or later
- A Gmail account
- An MCP client (e.g. [Claude Desktop](https://claude.ai/download))

### 1. Clone & install

```bash
git clone https://github.com/Abhitkumar89/Gmail_MCP_Tool.git
cd Gmail_MCP_Tool
npm install
```

### 2. Configure environment

```bash
cp .env.example .env
```

Edit `.env` with your values:

```env
# Required for sending
GMAIL_USER=your_email@gmail.com
GMAIL_APP_PASSWORD=your_16_char_app_password

# Required for reading / archiving / deleting
GMAIL_CLIENT_ID=your_client_id
GMAIL_CLIENT_SECRET=your_client_secret
GMAIL_REDIRECT_URI=https://developers.google.com/oauthplayground
GMAIL_REFRESH_TOKEN=your_refresh_token
```

<details>
<summary><strong>How to get a Gmail App Password</strong></summary>

1. Open [Google Account → Security](https://myaccount.google.com/security)
2. Enable **2-Step Verification**
3. Open **App passwords** → create one for **Mail**
4. Paste the 16-character password into `GMAIL_APP_PASSWORD`

</details>

<details>
<summary><strong>How to get OAuth2 credentials</strong></summary>

1. Create a project in [Google Cloud Console](https://console.cloud.google.com/)
2. Enable the **Gmail API**
3. Create OAuth 2.0 Client credentials
4. Use [OAuth 2.0 Playground](https://developers.google.com/oauthplayground) (or your own flow) to obtain a **refresh token**
5. Recommended scope: `https://www.googleapis.com/auth/gmail.modify`
6. Fill in `GMAIL_CLIENT_ID`, `GMAIL_CLIENT_SECRET`, `GMAIL_REDIRECT_URI`, and `GMAIL_REFRESH_TOKEN`

> **Note:** Sending uses App Password (SMTP). Inbox tools require OAuth2. For the full toolset, configure both.

</details>

### 3. Run the server

```bash
npm start
```

You should see:

```text
Gmail MCP Server running on stdio
```

The process waits on stdin — that is expected for MCP servers.

---

## MCP Client Configuration

Add the server to your Claude Desktop config (or any MCP-compatible client).

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/absolute/path/to/gmail-mcp-server/index.js"],
      "cwd": "/absolute/path/to/gmail-mcp-server"
    }
  }
}
```

> Set `cwd` to the project root so `.env` and `templates/` resolve correctly. Restart the client after saving.

---

## Usage Examples

Once connected, try prompts like:

```text
Send an introduction email to someone@example.com
Check if my Gmail configuration is working
Send an email to someone@example.com with subject "Hello" and body "Test message"
List unread emails
List unread emails with query "from:recruiter"
Get email with id 18c5b9b1a2e3a4b5
Archive email with id 18c5b9b1a2e3a4b5
Delete email with id 18c5b9b1a2e3a4b5
List email templates
Send a template email to user@example.com using template introduction
  with variables {"name":"Alex","recipientName":"Jordan","customMessage":"Great meeting you."}
```

---

## Email Templates

Templates live in `templates/` as `.txt` files. An optional first line sets the subject:

```text
Subject: Introduction - {{name}}

Dear {{recipientName}},

I hope this message finds you well. I'm {{name}}, reaching out to introduce myself...

{{customMessage}}

Best regards,
{{name}}
```

Pass variables through the `send_template_email` tool; Mustache replaces `{{placeholders}}`.

---

## Security

- Never commit `.env` — it is listed in `.gitignore`
- Use App Passwords and OAuth refresh tokens only on trusted machines
- Prefer least-privilege Gmail scopes where possible
- `delete_email` moves messages to **Trash** (recoverable), not permanent delete

---

## Scripts

| Command | Description |
|---|---|
| `npm start` | Start the MCP server |
| `npm run dev` | Start with Node `--watch` for local development |

---

## License

MIT — feel free to use and adapt for your own MCP projects.

---

<p align="center">
  Built to explore the Model Context Protocol · Node.js · Gmail API
</p>