This MCP server integrates with Gmail APIs to list, delete, summarize, and send emails and labels.
- 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
- 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.
- Run
npm install
from the root directory to install all required dependencies.
- Build the project:
- Run
npm run build
from the root repo directory.
- Run
- 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 likeError: No refresh token is set.
- Credentials will be saved in the root of this repo with file name
gmail-server-credentials.json
- Run
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
}
}
}
}
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.
GMAIL_OAUTH_PATH
: Absolute path to your Gmail OAuth credentials JSON file (e.g.,gmail-server-credentials.json
).ENABLE_RAG
: Set totrue
to enable Retrieval-Augmented Generation (RAG) features; otherwise, set tofalse
.
-
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)
To enable semantic search and RAG features:
-
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.
- This command mounts a local directory (
-
Or follow the Chroma DB documentation for other setup options.
-
Reference:
-
-
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.
- Whenever you use any of the following tools:
-
Performing vector search
- Use the
vector-search-emails
tool to semantically search your indexed emails using natural language queries.
- Use the
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.
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.