GM
Communication

Gmail MCP Server for Claude Desktop Auto Authentication

Enable Gmail integration in Claude Desktop with an MCP server offering seamless auto authentication for secure, instant access.

View on GitHub
Quick Install
npx -y @GongRzhe/Gmail-MCP-Server

Overview

This MCP (Model Context Protocol) server provides a lightweight bridge that enables Gmail access inside Claude Desktop via automatic authentication. It runs a small web service that performs the Google OAuth2 flow, stores tokens locally (or in a configured store), and exposes an MCP-compatible descriptor and endpoints that Claude Desktop can query to obtain an authenticated Gmail tool. The result is seamless, instant access to Gmail capabilities from Claude without manual token copy-paste.

The server is intended for developers and power users who run Claude Desktop locally and want a secure, automated way to let Claude access their Gmail account. It is small, configurable, and designed to be run on a local machine or private server. You will need Google API credentials and to register the server callback URL with Google OAuth to complete setup.

Features

  • Implements an MCP-compatible descriptor for Claude Desktop to discover Gmail tooling
  • Handles Google OAuth2 authorization and token refresh automatically
  • Simple configuration via environment variables or .env file
  • Runs locally (default) or on a remote host behind HTTPS
  • Minimal dependencies and easy to run with npm or Docker
  • Basic token storage (local file) with hooks for integrating custom stores

Installation / Configuration

Requirements: Node.js (16+), npm, a Google Cloud OAuth client (Web application) with an authorized redirect URI.

  1. Clone the repository and install dependencies:
git clone https://github.com/GongRzhe/Gmail-MCP-Server.git
cd Gmail-MCP-Server
npm install
  1. Create Google OAuth credentials:
  • Go to Google Cloud Console > APIs & Services > Credentials
  • Create OAuth 2.0 Client ID (type: Web application)
  • Add an authorized redirect URI: http://localhost:3000/auth/callback (adjust if running on other host/port)
  1. Create a .env file (example):
# .env
PORT=3000
GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-client-secret
REDIRECT_URI=http://localhost:3000/auth/callback
TOKEN_STORE=./tokens.json
HOST=http://localhost:3000
  1. Start the server:
npm start
# or for development
npm run dev
  1. Authorize the Gmail account:
  • Open http://localhost:3000/auth (or the server’s host) in your browser
  • Complete Google’s consent screen to allow the server to access Gmail scopes
  • Once authorized, the server stores the access/refresh token and advertises the tool via MCP

Docker usage:

docker build -t gmail-mcp-server .
docker run -p 3000:3000 \
  -e GOOGLE_CLIENT_ID=... \
  -e GOOGLE_CLIENT_SECRET=... \
  -e REDIRECT_URI=http://localhost:3000/auth/callback \
  gmail-mcp-server

Environment variables summary:

VariableDescription
PORTHTTP port the server listens on (default: 3000)
GOOGLE_CLIENT_IDOAuth2 client ID from Google Cloud Console
GOOGLE_CLIENT_SECRETOAuth2 client secret
REDIRECT_URIOAuth2 redirect/callback URI registered with Google
TOKEN_STOREPath to local token storage file
HOSTPublic host URL used in MCP descriptor (e.g., https://example.com)

Available Resources

  • Repository: https://github.com/GongRzhe/Gmail-MCP-Server
  • Google OAuth2 docs: https://developers.google.com/identity/protocols/oauth2
  • MCP specification / examples: check Claude Desktop documentation for MCP/tool integration (refer to your Claude client version)

Typical endpoints exposed by the server (default paths):

  • GET /mcp — MCP descriptor JSON listing available tools and endpoints
  • GET /auth — starts Google OAuth authorization
  • GET /auth/callback — OAuth callback used by Google to return authorization code
  • GET /status — simple health + auth status
  • POST /logout — clear stored tokens

(The exact endpoint paths are provided by the project; consult the repository for the current routes and descriptor format.)

Use Cases

  1. Quick personal setup for reading recent mail
  • Run the server locally, authorize your Gmail account through /auth.
  • In Claude Desktop, point the MCP integration URL to http://localhost:3000/mcp (or the HOST you configured).
  • Claude can then fetch recent emails, summarize conversations, and present context during chats.
  1. Draft and send email via assistant
  • With OAuth scopes for sending mail, Claude can compose drafts or send messages when prompted.
  • Useful for automating routine replies, drafting templates, or preparing multi-step email workflows that benefit from AI assistance.
  1. Search and summarize threads for research
  • Use Claude to search your mailbox for messages matching keywords, then request a concise summary of matched threads.
  • The server supplies the authenticated access so Claude can query Gmail APIs directly.
  1. Remote development/test environment
  • Run the server on a secure remote host with HTTPS, configure Google redirect URIs accordingly, and share the MCP endpoint with your team’s Claude Desktop instances (ensure token ownership and security policies are appropriate).

Security and Best Practices

  • Use HTTPS in production; browsers and OAuth require secure redirects for non-local hosts.
  • Restrict OAuth client to authorized redirect URIs and limit scopes to only what’s necessary (e.g., readonly if sending is not required).
  • Protect the token store (file permissions or external secrets manager).
  • If sharing the server with others, implement access controls or run separate instances per user to avoid token leakage.

For full implementation details, endpoint schemas, and advanced configuration, see the project repository: https://github.com/GongRzhe/Gmail-MCP-Server.

Tags:communication