# kasturimaheshbabu2316-mc/gmail-mcp-server architecture

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

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

## Overview

This is an MCP server that lets an AI client operate on a Gmail account. The principal workflow is a client tool request handled by the server, which validates and performs Gmail API operations, then returns results through MCP. Authentication is a separate setup flow that obtains OAuth tokens and stores credentials. Email composition helpers, label management, and filter management are distinct internal layers. The README documents additional message and batch capabilities; the sampled server excerpt is partial, so those operations are represented at the server boundary rather than as inferred internal call chains.

Main entry points: [`src/index.ts`](https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/index.ts) (MCP tool server), [`src/utl.ts`](https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/utl.ts) (Message composition), [`src/label-manager.ts`](https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/label-manager.ts) (Label management), [`src/filter-manager.ts`](https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/filter-manager.ts) (Filter management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["MCP runtime"]
  node_server["MCP tool server<br/>[index.ts]"]
end

subgraph group_auth["Authentication"]
  node_authflow["OAuth setup<br/>[index.ts]"]
  node_credentials["Credential files"]
end

subgraph group_email["Email operations"]
  node_emailtools["Email tools<br/>[index.ts]"]
  node_composition["Message composition<br/>[utl.ts]"]
  node_readsearch["Read and search<br/>[index.ts]"]
  node_messageactions["Message actions<br/>[index.ts]"]
  node_attachments["Attachment handling<br/>[index.ts]"]
end

subgraph group_organization["Mailbox organization"]
  node_labels["Label management<br/>[label-manager.ts]"]
  node_filters["Filter management<br/>[filter-manager.ts]"]
end

node_client(("AI client"))
node_gmail["Gmail API"]
node_oauth["Google OAuth"]
node_browser(("Browser"))
node_localfiles["Local files"]

node_client -->|"sends MCP requests"| node_server
node_server -->|"returns tool results"| node_client
node_server -->|"starts auth mode"| node_authflow
node_authflow -->|"requests tokens"| node_oauth
node_authflow -->|"opens consent"| node_browser
node_oauth -->|"returns tokens"| node_authflow
node_authflow -->|"stores credentials"| node_credentials
node_credentials -->|"loads credentials"| node_server
node_server -->|"dispatches email tools"| node_emailtools
node_emailtools -->|"builds raw messages"| node_composition
node_composition -->|"returns message"| node_emailtools
node_emailtools -->|"sends or drafts"| node_gmail
node_emailtools -->|"dispatches read/search"| node_readsearch
node_readsearch -->|"fetches messages"| node_gmail
node_emailtools -->|"dispatches actions"| node_messageactions
node_messageactions -->|"updates messages"| node_gmail
node_emailtools -->|"dispatches downloads"| node_attachments
node_attachments -->|"fetches attachment data"| node_gmail
node_attachments -->|"writes downloads"| node_localfiles
node_server -->|"calls label operations"| node_labels
node_labels -->|"manages labels"| node_gmail
node_server -->|"calls filter operations"| node_filters
node_filters -->|"manages filters"| node_gmail

click node_server "https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/index.ts"
click node_authflow "https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/index.ts"
click node_emailtools "https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/index.ts"
click node_composition "https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/utl.ts"
click node_readsearch "https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/index.ts"
click node_messageactions "https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/index.ts"
click node_attachments "https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/index.ts"
click node_labels "https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/label-manager.ts"
click node_filters "https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/filter-manager.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_client,node_browser toneBlue
class node_authflow,node_credentials toneAmber
class node_emailtools,node_composition,node_readsearch,node_messageactions,node_attachments,node_gmail toneMint
class node_labels,node_filters toneRose
class node_oauth,node_localfiles toneIndigo
```

## Components

### MCP runtime

- [MCP tool server](https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/index.ts): `src/index.ts`

### Authentication

- [OAuth setup](https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/index.ts): `src/index.ts`
- **Credential files**

### Email operations

- [Email tools](https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/index.ts): `src/index.ts`
- [Message composition](https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/utl.ts): `src/utl.ts`
- [Read and search](https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/index.ts): `src/index.ts`
- [Message actions](https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/index.ts): `src/index.ts`
- [Attachment handling](https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/index.ts): `src/index.ts`

### Mailbox organization

- [Label management](https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/label-manager.ts): `src/label-manager.ts`
- [Filter management](https://github.com/kasturimaheshbabu2316-mc/gmail-mcp-server/blob/main/src/filter-manager.ts): `src/filter-manager.ts`

### Other components

- **AI client**
- **Gmail API**
- **Google OAuth**
- **Browser**
- **Local files**

## Connections

- AI client → MCP tool server: sends MCP requests
- MCP tool server → AI client: returns tool results
- MCP tool server → OAuth setup: starts auth mode
- OAuth setup → Google OAuth: requests tokens
- OAuth setup → Browser: opens consent
- Google OAuth → OAuth setup: returns tokens
- OAuth setup → Credential files: stores credentials
- Credential files → MCP tool server: loads credentials
- MCP tool server → Email tools: dispatches email tools
- Email tools → Message composition: builds raw messages
- Message composition → Email tools: returns message
- Email tools → Gmail API: sends or drafts
- Email tools → Read and search: dispatches read/search
- Read and search → Gmail API: fetches messages
- Email tools → Message actions: dispatches actions
- Message actions → Gmail API: updates messages
- Email tools → Attachment handling: dispatches downloads
- Attachment handling → Gmail API: fetches attachment data
- Attachment handling → Local files: writes downloads
- MCP tool server → Label management: calls label operations
- Label management → Gmail API: manages labels
- MCP tool server → Filter management: calls filter operations
- Filter management → Gmail API: manages filters