Ayush-k-Shukla/gmail-mcp-server

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": ["<absolute path to dist/mcp.js>"],
      "env": {
        "GMAIL_OAUTH_PATH": "<absolute path to gmail-server-credentials.json>",
        "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": ["<absolute path to dist/mcp.js>"],
      "env": {
        "GMAIL_OAUTH_PATH": "<absolute path to gmail-server-credentials.json>",
        "ENABLE_RAG": "false" // mark as true if want to use rag
      }
    }
  }
}

Replace the placeholders (<absolute path ...>) 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

  • userId: The user Gmail ID (string, required)

• send-email: Send an email to a given email address (supports attachments and HTML)

  • to: Recipient email address (string, required)
  • subject: Email subject (string, required)
  • body: Email body (string, required)
  • isHtml: Send as HTML email (boolean, optional, default: false)
  • attachments: Array of attachments (base64 encoded, optional)
    • filename: Attachment filename (string, required)
    • mimeType: MIME type (string, required)
    • content: Base64 encoded content (string, required)

• create-label: Create a new Gmail label

  • name: Label name (string, required)

• delete-email: Delete an email by message ID

  • messageId: ID of the email message (string, required)

• summarize-top-k-emails: Summarize the top k emails in the inbox

  • k: Number of top emails to summarize (number, required)

• get-unread-emails: Get unread emails from the inbox

  • maxResults: Maximum number of unread emails to fetch (number, optional, default: 10)

• global-search-emails: Search emails by subject, sender/recipient, time range, keyword, and label

  • subject: Subject to search for (string, optional)
  • sender: Sender email address (string, optional)
  • recipient: Recipient email address (string, optional)
  • after: Start date (YYYY/MM/DD) (string, optional)
  • before: End date (YYYY/MM/DD) (string, optional)
  • keyword: Keyword in body/snippet (string, optional)
  • label: Gmail label to filter by (string, optional)
  • maxResults: Maximum results (number, optional, default: 10)

• list-gmail-labels: List all Gmail labels for the authenticated user

  • No parameters required

• delete-gmail-label: Delete an gmail label by label ID

  • labelId: ID of the label (string, required)

• vector-search-emails: Semantic search for emails using vector embeddings (RAG)

  • query: The search query (string, required)
  • k: Number of top results to return (number, optional, default: 10)

Running with Retrieval-Augmented Generation (RAG)

To enable semantic search and RAG features:

1. Run Chroma DB locally

   • Start a local Chroma DB instance for embedding storage and retrieval. You can use Docker:

     docker run -v ./chroma-data:/data -p 8000:8000 chromadb/chroma
     

     • This command mounts a local directory (./chroma-data) to the container's /data directory, ensuring your Chroma DB data persists even if the container is stopped or removed.
     • If you do not use the -v option, your data will be lost when the container is deleted.

   • Or follow the Chroma DB documentation for other setup options.

   • Reference:

     • Chroma DB Docker Quickstart
     • Chroma DB TypeScript Client

2. Indexing emails for embeddings

   • Whenever you use any of the following tools:
     • global-search-emails
     • summarize-top-k-emails
     • get-unread-emails
   • The emails fetched will be automatically indexed and embedded into Chroma DB for future semantic search.

3. Performing vector search

   • Use the vector-search-emails tool to semantically search your indexed emails using natural language queries.

Note:

• Ensure Chroma DB is running before using RAG features.
• Only emails fetched through the above tools are indexed for semantic search.
• For best results, first fetch new emails to keep the index updated.

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 semantic<br/>search query<br/><b>(Triggered from LLM)</b>"]

    %% Query Flow
    Query --> CheckIndexed{"Emails already<br/>indexed?"}
    CheckIndexed -- No --> Fetch["Fetch emails<br/>from Gmail API"]
    Fetch --> Embed["Generate embeddings<br/>using xenova"]
    Embed --> Index["Index embeddings<br/>in Chroma DB"]
    Index --> Searchable["Emails are now<br/>searchable semantically"]
    Searchable --> QEmbed["Generate embedding<br/>for query"]

    CheckIndexed -- Yes --> QEmbed
    QEmbed --> QSearch["Query Chroma DB<br/>for similar emails"]
    QSearch --> Result["Return matching emails"]

• LLM Role: The user interacts with the LLM, which interprets the query and calls the appropriate MCP server tools (such as semantic search or email fetch).
• Embedding: When emails are fetched, their content is converted into vector embeddings using Xenova.
• Indexing: These embeddings are stored in Chroma DB for fast retrieval.
• Semantic Search: When the LLM uses vector-search-emails, the query is embedded and compared to indexed emails to find the most relevant matches.