gmail

This Gmail MCP server provides programmatic access to Gmail through a set of tools that let you list, delete, summarize, and send emails, as well as manage Gmail labels. It also supports optional Retrieval-Augmented Generation (RAG) features by indexing emails with an embedded vector store (Chroma DB) and enabling semantic search. You can run the server locally and wire it into editors or CLIs that support MCP servers. Use the tools via MCP calls exposed by the server to perform common email tasks without switching contexts.

Key capabilities include getting Gmail profile details, sending emails (including attachments and HTML content), creating and deleting labels, deleting emails by message ID, summarizing the top-k emails in your inbox, fetching unread emails, and performing global searches by subject, sender/recipient, time range, keywords, and label. For advanced usage, you can enable RAG and perform vector-based semantic searches over indexed emails using vector-search-emails. Ensure you have the Gmail OAuth credentials configured and accessible at the path you provide to the GMAIL_OAUTH_PATH environment variable.

Prerequisites:

• Node.js v18 or higher and npm installed
• Optional: Docker if you plan to run RAG components like Chroma DB locally

1. Clone the repository or obtain the server files locally.
2. Install dependencies from the project root:

npm install

3. Prepare Google Cloud OAuth credentials:

• Create a Google Cloud project and enable the Gmail API
• Create OAuth Client ID for Web App, download the JSON, rename to gmail-server-credentials.json, and place it at the repo root or a path you will reference via GMAIL_OAUTH_PATH

4. Build the project (if applicable):

npm run build

5. Run or attach the MCP server via your MCP host (e.g., in VS Code settings):

• Ensure the dist/mcp.js path is correct for your environment
• Provide the GMAIL_OAUTH_PATH pointing to your credentials file
• Optionally set ENABLE_RAG to true to enable RAG features if you have Chroma DB running

6. Validate Authentication:

node dist/mcp.js auth

This will initiate the OAuth flow in your browser and produce credentials stored at the specified path.

Notes and tips:

• The Gmail OAuth credentials file is essential for authentication and access to Gmail data. Keep it secure and avoid committing it to VCS.
• When ENABLE_RAG is true, ensure Chroma DB is running (e.g., via Docker) and accessible to the MCP server; the README shows a Docker run example for Chroma DB.
• The access token is time-bound; re-authenticate if you see errors about missing refresh tokens.
• For best results with RAG features, periodically fetch new emails so that embeddings stay up to date in the vector store.
• When wiring into editors or clients, use absolute paths for both the dist/mcp.js and the Gmail OAuth credentials path to avoid path resolution issues.