How gongrzhe/gmail-mcp-server works
Project type and purpose
• This is a Node.js-based Model Context Protocol (MCP) server delivered as a CLI module.
• It provides a bridge between a user (via Claude Desktop or Docker) and the Gmail API, exposing a suite of email- and label-management commands.
File structure
• Top-level configuration and metadata:
– Dockerfile, docker-compose.yml (container support)
– package.json, tsconfig.json (build and dependency definitions)
– smithery.yaml, mcp-config.json (MCP server metadata)
• src/ folder (TypeScript source):
– index.ts (entry point / command dispatcher)
– label-manager.ts (encapsulates Gmail label operations)
– utl.ts (generic HTTP / API helper functions)
– evals/evals.ts (test harness for MCP evals)
• setup.js (installation helper)
• External files ignored (.gitignore, .npmignore)
Extract architectural insights from the README
• Core responsibilities:
– OAuth2 “auto browser launch” authentication flow with an embedded HTTP callback server on port 3000
– Persistent credential storage under ~/.gmail-mcp
– Suite of “tools” (send_email, read_email, search_emails, modify_label, batch operations, etc.)
• Deployment options: local CLI (npx), Docker container, cloud with reverse proxy
• External dependencies: Google OAuth2 endpoints, Gmail REST API
Main components and their relationships
a. User / Client Layer
– Claude Desktop (invokes npx @gongrzhe/server-gmail-autoauth-mcp or Docker command)
– Optional: cloud reverse proxy / DNS for custom OAuth callbacks
b. CLI / MCP Server Process
– index.ts (parses JSON commands, routes to appropriate handler)
– setup.js (initial installation / config scaffolding)
c. Core Library Modules
– label-manager.ts (CRUD operations on Gmail labels)
– utl.ts (generic wrappers around Gmail API calls, HTTP utilities)
– evals package (invokes index.ts for automated tests)
d. OAuth2 Authorization Flow
– Embedded HTTP server listening on localhost:3000 (or custom callback URL)
– Browser launch → Google’s OAuth2 endpoint → redirect with code → callback handler → token exchange
– Credential persistence in file system (~/.gmail-mcp/credentials.json)
e. External Service
– Gmail REST API (https://www.googleapis.com/gmail/v1)
– Google OAuth2 Authorization Server
Architectural patterns and design principles
• Separation of concerns: distinct modules for command dispatch (index.ts), label management, generic API utilities
• Adapter pattern: utl.ts wraps raw HTTP calls into higher-level functions consumed by business logic
• CLI as a thin front-end: all business logic lives in TypeScript modules, enabling reuse in evals/tests
• Asynchronous, event-driven I/O (Node.js) for non-blocking API interactions and batch processing
Elements
– Client (Claude Desktop / Docker)
– CLI Server (index.ts / setup.js)
– Library modules (label-manager.ts, utl.ts)
– OAuth2 Callback Server
– JSON command input → dispatcher → module → external API → JSON response back
– OAuth2 browser launch → authorization endpoint → callback → token storage
– Blue for in-process components (CLI, modules)
– Green for external systems (Google OAuth2, Gmail API)
– Grey for persistent storage (credentials)
• Annotations for protocols and ports (e.g., HTTP callback on 3000, HTTPS to Google)