Gmail MCP server

This MCP server integrates with Gmail APIs to list, delete, summarize, and send emails and labels.

Prerequisites

• Node.js & npm: Ensure you have Node.js (v18 or higher recommended) and npm installed. Download Node.js
• Docker (for RAG/Chroma DB): If you want to use RAG features, install Docker: Get Docker

Getting started# Setup Google cloud project

• Create a Google Cloud project
• Enable the Gmail API
• Configure an OAuth consent screen
• If have workspace account then make it private
• Otherwise set some test users (emails against which want to test) to test before app is verified.
• Create an OAuth Client ID for application type "Web App"
• Download the JSON file of your client's OAuth keys
• Rename the key file to gcp-oauth-keys.json and place into the root of the repo.

Install dependencies

• Run npm install from the root directory to install all required dependencies.

How to Run

1. Build the project:

• Run npm run build from the root repo directory.

2. Authenticate:

• Run node dist/mcp.js auth
• This will open an authentication flow in your system browser
• Note down the token generated is only valid for 1 hr so relogin if get any error like Error: No refresh token is set.
• Credentials will be saved in the root of this repo with file name gmail-server-credentials.json

MCP Server Configuration Examples# VS Code settings.json

To use this server in VS Code, add the following to your settings.json:

{
  "mcpServers": {
    "gmail-mcp-server": {
      "type": "stdio",
      "command": "node",
      "args": [""],
      "env": {
        "GMAIL_OAUTH_PATH": "",
        "ENABLE_RAG": "false" // mark as true if want to use rag
      }
    }
  }
}

Claude Desktop claude_desktop_config.json

To use this server in Claude Desktop, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "gmail-mcp-server": {
      "type": "stdio",
      "command": "node",
      "args": [""],
      "env": {
        "GMAIL_OAUTH_PATH": "",
        "ENABLE_RAG": "false" // mark as true if want to use rag
      }
    }
  }
}

Replace the placeholders (``) with the actual full paths on your system for clarity and reliability.

Environment Variables

• GMAIL_OAUTH_PATH: Absolute path to your Gmail OAuth credentials JSON file (e.g., gmail-server-credentials.json).
• ENABLE_RAG: Set to true to enable Retrieval-Augmented Generation (RAG) features; otherwise, set to false.

Tools

• get-gmail-profile: Get Gmail profile details based on userId
• send-email: Send an email to a given email address (supports attachments and HTML)
• create-label: Create a new Gmail label
• delete-email: Delete an email by message ID
• summarize-top-k-emails: Summarize the top k emails in the inbox
• get-unread-emails: Get unread emails from the inbox
• global-search-emails: Search emails by subject, sender/recipient, time range, keyword, and label
• list-gmail-labels: List all Gmail labels for the authenticated user
• delete-gmail-label: Delete an gmail label by label ID
• vector-search-emails: Semantic search for emails using vector embeddings

Running with Retrieval-Augmented Generation (RAG)

To enable semantic search and RAG features:

1. Run Chroma DB locally
2. Indexing emails for embeddings
3. Performing vector search

RAG Flow: Embedding, Indexing, and Searching Emails

Below is a simplified Mermaid flowchart for how RAG is used to embed, index, and search emails:

flowchart TD
User[User] --> LLM["LLM (calls MCP tools)"]
LLM --> Query["User submits semanticsearch query(Triggered from LLM)"]
CheckIndexed{Emails alreadyindexed?} --> Fetch["Fetch emailsfrom Gmail API"]
Fetch --> Embed["Generate embeddingsusing xenova"]
Embed --> Index["Index embeddingsin Chroma DB"]
Index --> Searchable["Emails are nowsearchable semantically"]
Searchable --> QEmbed["Generate embeddingfor query"]
QEmbed --> QSearch["Query Chroma DBfor similar emails"]
QSearch --> Result["Return matching emails"]