# gongrzhe/gmail-mcp-server architecture

> Architecture diagram of the GitHub repository gongrzhe/gmail-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gongrzhe/gmail-mcp-server
- Repository: https://github.com/gongrzhe/gmail-mcp-server

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client Layer"
        direction TB
        Claude["Claude Desktop"]:::client
        subgraph "Docker Container Support"
            direction TB
            DockerFile["Dockerfile"]:::client
            DockerCompose["docker-compose.yml"]:::client
        end
    end

    subgraph "Node.js Process"
        direction TB
        Index["index.ts"]:::process
        Setup["setup.js"]:::process
        subgraph "Core Modules"
            direction TB
            LM["label-manager.ts"]:::process
            UTL["utl.ts"]:::process
        end
        Evals["evals test harness"]:::process
        OAuthServer["OAuth2 Callback Server\n(localhost:3000)"]:::process
    end

    subgraph "Configuration / Metadata"
        direction TB
        MCPConfig["mcp-config.json"]:::config
        Smithery["smithery.yaml"]:::config
        Package["package.json"]:::config
        TSConfig["tsconfig.json"]:::config
    end

    CredentialsStore[(credentials.json)]:::storage

    subgraph "External Services"
        direction TB
        AuthServer["Google OAuth2 Server"]:::external
        GmailAPI["Gmail REST API"]:::external
    end

    %% Flows
    Claude -->|"CLI command"| Index
    DockerFile -->|"docker run"| Index
    DockerCompose -->|"compose up"| Index

    Index -->|"dispatch command"| LM
    Index -->|"dispatch command"| UTL
    Evals -->|"invoke index.ts"| Index

    LM -->|"calls utl API"| UTL
    UTL -->|"HTTPS request"| GmailAPI
    UTL -->|"read/write tokens"| CredentialsStore

    Index -->|"start HTTP server"| OAuthServer
    OAuthServer -->|"browser redirect"| AuthServer
    AuthServer -->|"authorization code"| OAuthServer
    OAuthServer -->|"exchange code"| CredentialsStore
    CredentialsStore -->|"access token"| OAuthServer

    %% Click Events
    click Index "https://github.com/gongrzhe/gmail-mcp-server/blob/main/src/index.ts"
    click Setup "https://github.com/gongrzhe/gmail-mcp-server/blob/main/setup.js"
    click LM "https://github.com/gongrzhe/gmail-mcp-server/blob/main/src/label-manager.ts"
    click UTL "https://github.com/gongrzhe/gmail-mcp-server/blob/main/src/utl.ts"
    click Evals "https://github.com/gongrzhe/gmail-mcp-server/blob/main/src/evals/evals.ts"
    click DockerFile "https://github.com/gongrzhe/gmail-mcp-server/tree/main/Dockerfile"
    click DockerCompose "https://github.com/gongrzhe/gmail-mcp-server/blob/main/docker-compose.yml"
    click MCPConfig "https://github.com/gongrzhe/gmail-mcp-server/blob/main/mcp-config.json"
    click Smithery "https://github.com/gongrzhe/gmail-mcp-server/blob/main/smithery.yaml"
    click Package "https://github.com/gongrzhe/gmail-mcp-server/blob/main/package.json"
    click TSConfig "https://github.com/gongrzhe/gmail-mcp-server/blob/main/tsconfig.json"

    %% Styles
    classDef client fill:#D6E8FF,stroke:#0366d6,color:#000
    classDef process fill:#BEE3F8,stroke:#3182ce,color:#000
    classDef storage fill:#E2E8F0,stroke:#718096,color:#000
    classDef external fill:#C6F6D5,stroke:#2f855a,color:#000
    classDef config fill:#F0FFF4,stroke:#38A169,color:#000
```
