# j3k0/mcp-google-workspace architecture

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

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

## Overview

This is an MCP server that exposes multi-account Gmail and Google Calendar operations to an AI client. The main workflow is a client tool request, account/OAuth setup, dispatch to the Gmail or Calendar tool handler, then a Google API operation and a structured response. Gmail covers search, retrieval, drafts/replies, archiving, and attachment handling; Calendar covers calendar/event listing and event creation/deletion. The README documents these capabilities, while sampled source confirms the server routing, OAuth service, and tool implementations; some individual Gmail operations are not fully shown in the excerpts.

Main entry points: [`src/services/gauth.ts`](https://github.com/j3k0/mcp-google-workspace/blob/main/src/services/gauth.ts) (Google auth service), [`src/server.ts`](https://github.com/j3k0/mcp-google-workspace/blob/main/src/server.ts) (Workspace server), [`src/tools/gmail.ts`](https://github.com/j3k0/mcp-google-workspace/blob/main/src/tools/gmail.ts) (Gmail operations), [`src/tools/calendar.ts`](https://github.com/j3k0/mcp-google-workspace/blob/main/src/tools/calendar.ts) (Calendar operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["MCP Server"]
  node_server["Workspace server<br/>[server.ts]"]
  node_oauth_callback["OAuth callback<br/>[server.ts]"]
end

subgraph group_identity["Accounts &amp; OAuth"]
  node_auth_cli["Auth CLI<br/>[authenticate.ts]"]
  node_gauth["Google auth service<br/>[gauth.ts]"]
  node_credentials[("OAuth credentials<br/>[gauth.ts]")]
end

subgraph group_gmail["Gmail"]
  node_gmail_tools["Gmail operations<br/>[gmail.ts]"]
  node_gmail_helpers["Gmail formatting<br/>[gmail-helpers.ts]"]
  node_attachment_files[("Attachment files")]
end

subgraph group_calendar["Calendar"]
  node_calendar_tools["Calendar operations<br/>[calendar.ts]"]
end

node_client(("MCP client"))
node_google_oauth["Google OAuth"]
node_gmail_api["Gmail API"]
node_calendar_api["Calendar API"]

node_client -->|"sends tools"| node_server
node_server -->|"initializes auth"| node_gauth
node_server -->|"dispatches Gmail"| node_gmail_tools
node_server -->|"dispatches Calendar"| node_calendar_tools
node_server -->|"checks accounts"| node_gauth
node_server -->|"loads credentials"| node_gauth
node_server -->|"opens consent"| node_google_oauth
node_google_oauth -->|"returns code"| node_oauth_callback
node_oauth_callback -->|"exchanges code"| node_gauth
node_auth_cli -->|"authenticates accounts"| node_gauth
node_gauth -->|"requests tokens"| node_google_oauth
node_gauth -->|"reads and writes"| node_credentials
node_gmail_tools -->|"lists accounts"| node_gauth
node_calendar_tools -->|"lists accounts"| node_gauth
node_gmail_tools -->|"queries and updates"| node_gmail_api
node_gmail_tools -->|"formats content"| node_gmail_helpers
node_gmail_tools -->|"writes attachments"| node_attachment_files
node_calendar_tools -->|"reads and updates"| node_calendar_api

click node_server "https://github.com/j3k0/mcp-google-workspace/blob/main/src/server.ts"
click node_oauth_callback "https://github.com/j3k0/mcp-google-workspace/blob/main/src/server.ts"
click node_auth_cli "https://github.com/j3k0/mcp-google-workspace/blob/main/src/authenticate.ts"
click node_gauth "https://github.com/j3k0/mcp-google-workspace/blob/main/src/services/gauth.ts"
click node_credentials "https://github.com/j3k0/mcp-google-workspace/blob/main/src/services/gauth.ts"
click node_gmail_tools "https://github.com/j3k0/mcp-google-workspace/blob/main/src/tools/gmail.ts"
click node_gmail_helpers "https://github.com/j3k0/mcp-google-workspace/blob/main/src/tools/gmail-helpers.ts"
click node_calendar_tools "https://github.com/j3k0/mcp-google-workspace/blob/main/src/tools/calendar.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_oauth_callback,node_client toneBlue
class node_auth_cli,node_gauth,node_credentials toneAmber
class node_gmail_tools,node_gmail_helpers,node_attachment_files,node_gmail_api,node_calendar_api toneMint
class node_calendar_tools toneRose
class node_google_oauth toneIndigo
```

## Components

### MCP Server

- [Workspace server](https://github.com/j3k0/mcp-google-workspace/blob/main/src/server.ts): `src/server.ts`
- [OAuth callback](https://github.com/j3k0/mcp-google-workspace/blob/main/src/server.ts): `src/server.ts`

### Accounts & OAuth

- [Auth CLI](https://github.com/j3k0/mcp-google-workspace/blob/main/src/authenticate.ts): `src/authenticate.ts`
- [Google auth service](https://github.com/j3k0/mcp-google-workspace/blob/main/src/services/gauth.ts): `src/services/gauth.ts`
- [OAuth credentials](https://github.com/j3k0/mcp-google-workspace/blob/main/src/services/gauth.ts): `src/services/gauth.ts`

### Gmail

- [Gmail operations](https://github.com/j3k0/mcp-google-workspace/blob/main/src/tools/gmail.ts): `src/tools/gmail.ts`
- [Gmail formatting](https://github.com/j3k0/mcp-google-workspace/blob/main/src/tools/gmail-helpers.ts): `src/tools/gmail-helpers.ts`
- **Attachment files**

### Calendar

- [Calendar operations](https://github.com/j3k0/mcp-google-workspace/blob/main/src/tools/calendar.ts): `src/tools/calendar.ts`

### Other components

- **MCP client**
- **Google OAuth**
- **Gmail API**
- **Calendar API**

## Connections

- MCP client → Workspace server: sends tools
- Workspace server → Google auth service: initializes auth
- Workspace server → Gmail operations: dispatches Gmail
- Workspace server → Calendar operations: dispatches Calendar
- Workspace server → Google auth service: checks accounts
- Workspace server → Google auth service: loads credentials
- Workspace server → Google OAuth: opens consent
- Google OAuth → OAuth callback: returns code
- OAuth callback → Google auth service: exchanges code
- Auth CLI → Google auth service: authenticates accounts
- Google auth service → Google OAuth: requests tokens
- Google auth service → OAuth credentials: reads and writes
- Gmail operations → Google auth service: lists accounts
- Calendar operations → Google auth service: lists accounts
- Gmail operations → Gmail API: queries and updates
- Gmail operations → Gmail formatting: formats content
- Gmail operations → Attachment files: writes attachments
- Calendar operations → Calendar API: reads and updates