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

  +------------------+          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 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

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 18 or later
• A Gmail account
• An MCP client (e.g. Claude Desktop)

1. Clone & install

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

2. Configure environment

cp .env.example .env

Edit .env with your values:

# 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
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
2. Enable the Gmail API
3. Create OAuth 2.0 Client credentials
4. Use OAuth 2.0 Playground (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

npm start

You should see:

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

{
  "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:

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:

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>