# prabud0401/google-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/prabud0401/google-mcp
- Repository: https://github.com/prabud0401/google-mcp

## Overview

Google MCP Server exposes Gmail operations to MCP-compatible clients over stdio. The principal workflow is a client tool request routed through the MCP server and tool dispatcher to Gmail operations, which authenticate and call the Gmail API before returning results. The service covers message listing, search, reading, sending, labels, drafts, and attachment downloads; MIME helpers decode message content. A separate CLI supports OAuth authorization. Source excerpts show these calls and credential handling; other capabilities are represented from the README, not unsampled implementation details.

Main entry points: [`src/auth.ts`](https://github.com/prabud0401/google-mcp/blob/main/src/auth.ts) (OAuth and Gmail Client), [`src/tools.ts`](https://github.com/prabud0401/google-mcp/blob/main/src/tools.ts) (Tool Dispatcher), [`src/gmail/service.ts`](https://github.com/prabud0401/google-mcp/blob/main/src/gmail/service.ts) (Read and Search), [`src/config.ts`](https://github.com/prabud0401/google-mcp/blob/main/src/config.ts) (Credential Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP Interface"]
  node_server["Stdio MCP Server<br/>[index.ts]"]
  node_tools["Tool Dispatcher<br/>[tools.ts]"]
end

subgraph group_gmail["Gmail Operations"]
  node_message_read["Read and Search<br/>[service.ts]"]
  node_message_write["Send and Draft<br/>[service.ts]"]
  node_labels["Label Operations<br/>[service.ts]"]
  node_attachments["Attachment Download<br/>[service.ts]"]
  node_mime["MIME Parsing<br/>[mime.ts]"]
end

subgraph group_auth["Authentication"]
  node_auth_cli["OAuth CLI<br/>[auth-cli.ts]"]
  node_auth_service["OAuth and Gmail Client<br/>[auth.ts]"]
  node_config["Credential Configuration<br/>[config.ts]"]
end

subgraph group_models["Data Models"]
  node_gmail_types["Gmail Data Types<br/>[types.ts]"]
end

node_client(("MCP Client"))
node_gmail_api["Gmail API"]
node_credentials[("Credential Files")]

node_client -->|"sends JSON-RPC"| node_server
node_server -->|"dispatches tools"| node_tools
node_tools -->|"calls read/search"| node_message_read
node_tools -->|"calls send/draft"| node_message_write
node_tools -->|"calls label tools"| node_labels
node_tools -->|"calls download"| node_attachments
node_message_read -->|"gets client"| node_auth_service
node_message_write -->|"gets client"| node_auth_service
node_labels -->|"gets client"| node_auth_service
node_attachments -->|"gets client"| node_auth_service
node_message_read -->|"reads messages"| node_gmail_api
node_message_write -->|"sends messages"| node_gmail_api
node_labels -->|"manages labels"| node_gmail_api
node_attachments -->|"fetches attachments"| node_gmail_api
node_message_read -->|"parses MIME"| node_mime
node_mime -->|"uses attachment type"| node_gmail_types
node_message_read -->|"returns message types"| node_gmail_types
node_auth_cli -->|"creates OAuth client"| node_auth_service
node_auth_cli -->|"gets credential path"| node_config
node_auth_service -->|"loads OAuth config"| node_config
node_auth_service -->|"reads and writes tokens"| node_credentials
node_config -->|"resolves file paths"| node_credentials
node_auth_service -->|"creates authenticated client"| node_gmail_api

click node_server "https://github.com/prabud0401/google-mcp/blob/main/src/index.ts"
click node_tools "https://github.com/prabud0401/google-mcp/blob/main/src/tools.ts"
click node_message_read "https://github.com/prabud0401/google-mcp/blob/main/src/gmail/service.ts"
click node_message_write "https://github.com/prabud0401/google-mcp/blob/main/src/gmail/service.ts"
click node_labels "https://github.com/prabud0401/google-mcp/blob/main/src/gmail/service.ts"
click node_attachments "https://github.com/prabud0401/google-mcp/blob/main/src/gmail/service.ts"
click node_mime "https://github.com/prabud0401/google-mcp/blob/main/src/gmail/mime.ts"
click node_auth_cli "https://github.com/prabud0401/google-mcp/blob/main/src/auth-cli.ts"
click node_auth_service "https://github.com/prabud0401/google-mcp/blob/main/src/auth.ts"
click node_config "https://github.com/prabud0401/google-mcp/blob/main/src/config.ts"
click node_gmail_types "https://github.com/prabud0401/google-mcp/blob/main/src/gmail/types.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_tools,node_client toneBlue
class node_message_read,node_message_write,node_labels,node_attachments,node_mime,node_credentials toneAmber
class node_auth_cli,node_auth_service,node_config,node_gmail_api toneMint
class node_gmail_types toneRose
```

## Components

### MCP Interface

- [Stdio MCP Server](https://github.com/prabud0401/google-mcp/blob/main/src/index.ts): `src/index.ts`
- [Tool Dispatcher](https://github.com/prabud0401/google-mcp/blob/main/src/tools.ts): `src/tools.ts`

### Gmail Operations

- [Read and Search](https://github.com/prabud0401/google-mcp/blob/main/src/gmail/service.ts): `src/gmail/service.ts`
- [Send and Draft](https://github.com/prabud0401/google-mcp/blob/main/src/gmail/service.ts): `src/gmail/service.ts`
- [Label Operations](https://github.com/prabud0401/google-mcp/blob/main/src/gmail/service.ts): `src/gmail/service.ts`
- [Attachment Download](https://github.com/prabud0401/google-mcp/blob/main/src/gmail/service.ts): `src/gmail/service.ts`
- [MIME Parsing](https://github.com/prabud0401/google-mcp/blob/main/src/gmail/mime.ts): `src/gmail/mime.ts`

### Authentication

- [OAuth CLI](https://github.com/prabud0401/google-mcp/blob/main/src/auth-cli.ts): `src/auth-cli.ts`
- [OAuth and Gmail Client](https://github.com/prabud0401/google-mcp/blob/main/src/auth.ts): `src/auth.ts`
- [Credential Configuration](https://github.com/prabud0401/google-mcp/blob/main/src/config.ts): `src/config.ts`

### Data Models

- [Gmail Data Types](https://github.com/prabud0401/google-mcp/blob/main/src/gmail/types.ts): `src/gmail/types.ts`

### Other components

- **MCP Client**
- **Gmail API**
- **Credential Files**

## Connections

- MCP Client → Stdio MCP Server: sends JSON-RPC (evidence: `README.md`)
- Stdio MCP Server → Tool Dispatcher: dispatches tools (evidence: `src/index.ts`)
- Tool Dispatcher → Read and Search: calls read/search (evidence: `src/tools.ts`)
- Tool Dispatcher → Send and Draft: calls send/draft (evidence: `src/tools.ts`)
- Tool Dispatcher → Label Operations: calls label tools (evidence: `src/tools.ts`)
- Tool Dispatcher → Attachment Download: calls download (evidence: `src/tools.ts`)
- Read and Search → OAuth and Gmail Client: gets client (evidence: `src/gmail/service.ts`)
- Send and Draft → OAuth and Gmail Client: gets client (evidence: `src/gmail/service.ts`)
- Label Operations → OAuth and Gmail Client: gets client (evidence: `src/gmail/service.ts`)
- Attachment Download → OAuth and Gmail Client: gets client (evidence: `src/gmail/service.ts`)
- Read and Search → Gmail API: reads messages (evidence: `src/gmail/service.ts`)
- Send and Draft → Gmail API: sends messages (evidence: `src/gmail/service.ts`)
- Label Operations → Gmail API: manages labels (evidence: `src/gmail/service.ts`)
- Attachment Download → Gmail API: fetches attachments (evidence: `src/gmail/service.ts`)
- Read and Search → MIME Parsing: parses MIME (evidence: `src/gmail/service.ts`)
- MIME Parsing → Gmail Data Types: uses attachment type (evidence: `src/gmail/mime.ts`)
- Read and Search → Gmail Data Types: returns message types (evidence: `src/gmail/service.ts`)
- OAuth CLI → OAuth and Gmail Client: creates OAuth client (evidence: `src/auth-cli.ts`)
- OAuth CLI → Credential Configuration: gets credential path (evidence: `src/auth-cli.ts`)
- OAuth and Gmail Client → Credential Configuration: loads OAuth config (evidence: `src/auth.ts`)
- OAuth and Gmail Client → Credential Files: reads and writes tokens (evidence: `src/auth.ts`)
- Credential Configuration → Credential Files: resolves file paths (evidence: `src/config.ts`)
- OAuth and Gmail Client → Gmail API: creates authenticated client (evidence: `src/auth.ts`)
