gmail-workspace-mcp-server 0.0.3

package/README.md

@@ -0,0 +1,141 @@
+# Gmail Workspace MCP Server
+
+An MCP (Model Context Protocol) server that provides Gmail integration for AI assistants using Google Workspace service accounts with domain-wide delegation.
+
+## Features
+
+- **List Recent Emails**: Retrieve recent emails within a specified time horizon
+- **Get Email Details**: Fetch full email content including body and attachments info
+- **Service Account Authentication**: Secure domain-wide delegation for Google Workspace organizations
+
+## Installation
+
+```bash
+npm install gmail-workspace-mcp-server
+```
+
+Or run directly with npx:
+
+```bash
+npx gmail-workspace-mcp-server
+```
+
+## Prerequisites
+
+This server requires a Google Cloud service account with domain-wide delegation to access Gmail on behalf of users in your Google Workspace domain.
+
+### Setup Steps
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create or select a project
+3. Enable the Gmail API
+4. Create a service account with domain-wide delegation enabled
+5. In [Google Workspace Admin Console](https://admin.google.com/), grant the service account access to the `https://www.googleapis.com/auth/gmail.readonly` scope
+6. Download the JSON key file
+
+### Environment Variables
+
+| Variable                             | Required | Description                              |
+| ------------------------------------ | -------- | ---------------------------------------- |
+| `GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL` | Yes      | Service account email address            |
+| `GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY`  | Yes      | Service account private key (PEM format) |
+| `GMAIL_IMPERSONATE_EMAIL`            | Yes      | Email address to impersonate             |
+
+You can find the `client_email` and `private_key` values in your service account JSON key file.
+
+## Configuration
+
+### Claude Desktop
+
+Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "gmail": {
+      "command": "npx",
+      "args": ["gmail-workspace-mcp-server"],
+      "env": {
+        "GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL": "my-service-account@my-project.iam.gserviceaccount.com",
+        "GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----",
+        "GMAIL_IMPERSONATE_EMAIL": "user@yourdomain.com"
+      }
+    }
+  }
+}
+```
+
+**Note:** For the private key, you can either:
+
+1. Use the key directly with `\n` for newlines (as shown above)
+2. Set the environment variable from a shell that preserves newlines
+
+## Available Tools
+
+### gmail_list_recent_emails
+
+List recent emails from Gmail within a specified time horizon.
+
+**Parameters:**
+
+- `hours` (number, optional): Time horizon in hours (default: 24)
+- `labels` (string, optional): Comma-separated label IDs (default: "INBOX")
+- `max_results` (number, optional): Maximum emails to return (default: 10, max: 100)
+
+**Example:**
+
+```json
+{
+  "hours": 48,
+  "labels": "INBOX,STARRED",
+  "max_results": 20
+}
+```
+
+### gmail_get_email
+
+Retrieve the full content of a specific email by its ID.
+
+**Parameters:**
+
+- `email_id` (string, required): The unique identifier of the email
+
+**Example:**
+
+```json
+{
+  "email_id": "18abc123def456"
+}
+```
+
+## Development
+
+### Setup
+
+```bash
+# Install dependencies
+npm run install-all
+
+# Build
+npm run build
+
+# Run in development mode
+npm run dev
+```
+
+### Testing
+
+```bash
+# Run functional tests
+npm test
+
+# Run integration tests
+npm run test:integration
+
+# Run manual tests (requires service account credentials)
+npm run test:manual
+```
+
+## License
+
+MIT

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.integration-with-mock.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.integration-with-mock.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * Integration test entry point with mock data
+ * Used for running integration tests without real Gmail API access
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createMCPServer } from '../shared/index.js';
+import { logServerStart, logError } from '../shared/logging.js';
+// =============================================================================
+// MOCK DATA
+// =============================================================================
+const MOCK_EMAILS = [
+    {
+        id: 'msg_001',
+        threadId: 'thread_001',
+        labelIds: ['INBOX', 'UNREAD'],
+        snippet: 'Hey, just wanted to check in about the project...',
+        historyId: '12345',
+        internalDate: String(Date.now() - 1000 * 60 * 30), // 30 minutes ago
+        payload: {
+            mimeType: 'text/plain',
+            headers: [
+                { name: 'Subject', value: 'Project Update' },
+                { name: 'From', value: 'alice@example.com' },
+                { name: 'To', value: 'me@example.com' },
+                { name: 'Date', value: new Date(Date.now() - 1000 * 60 * 30).toISOString() },
+            ],
+            body: {
+                size: 150,
+                data: Buffer.from('Hey, just wanted to check in about the project. How is everything going?').toString('base64url'),
+            },
+        },
+        sizeEstimate: 1024,
+    },
+    {
+        id: 'msg_002',
+        threadId: 'thread_002',
+        labelIds: ['INBOX'],
+        snippet: 'Meeting reminder for tomorrow at 2pm...',
+        historyId: '12346',
+        internalDate: String(Date.now() - 1000 * 60 * 60 * 2), // 2 hours ago
+        payload: {
+            mimeType: 'text/plain',
+            headers: [
+                { name: 'Subject', value: 'Meeting Reminder' },
+                { name: 'From', value: 'calendar@example.com' },
+                { name: 'To', value: 'me@example.com' },
+                { name: 'Date', value: new Date(Date.now() - 1000 * 60 * 60 * 2).toISOString() },
+            ],
+            body: {
+                size: 200,
+                data: Buffer.from('Meeting reminder for tomorrow at 2pm. Please confirm your attendance.').toString('base64url'),
+            },
+        },
+        sizeEstimate: 2048,
+    },
+];
+// =============================================================================
+// MOCK CLIENT
+// =============================================================================
+function createMockClient() {
+    return {
+        async listMessages(options) {
+            // Filter by label if specified
+            let filtered = MOCK_EMAILS;
+            if (options?.labelIds && options.labelIds.length > 0) {
+                filtered = MOCK_EMAILS.filter((email) => options.labelIds.some((label) => email.labelIds?.includes(label)));
+            }
+            // Apply maxResults
+            const maxResults = options?.maxResults ?? 10;
+            const messages = filtered.slice(0, maxResults).map((e) => ({
+                id: e.id,
+                threadId: e.threadId,
+            }));
+            return {
+                messages,
+                resultSizeEstimate: messages.length,
+            };
+        },
+        async getMessage(messageId, _options) {
+            const email = MOCK_EMAILS.find((e) => e.id === messageId);
+            if (!email) {
+                throw new Error(`Message not found: ${messageId}`);
+            }
+            return email;
+        },
+    };
+}
+// =============================================================================
+// MAIN ENTRY POINT
+// =============================================================================
+async function main() {
+    // Create server with mock client
+    const { server, registerHandlers } = createMCPServer();
+    // Register handlers with mock client factory
+    await registerHandlers(server, createMockClient);
+    // Start server with stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logServerStart('Gmail (Mock)');
+}
+// Run the server
+main().catch((error) => {
+    logError('main', error);
+    process.exit(1);
+});

package/build/index.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createMCPServer } from '../shared/index.js';
+import { logServerStart, logError } from '../shared/logging.js';
+// =============================================================================
+// ENVIRONMENT VALIDATION
+// =============================================================================
+function validateEnvironment() {
+    const missing = [];
+    if (!process.env.GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL) {
+        missing.push('GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL');
+    }
+    if (!process.env.GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY) {
+        missing.push('GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY');
+    }
+    if (!process.env.GMAIL_IMPERSONATE_EMAIL) {
+        missing.push('GMAIL_IMPERSONATE_EMAIL');
+    }
+    if (missing.length > 0) {
+        logError('validateEnvironment', 'Missing required environment variables:');
+        console.error('\nThis MCP server requires a Google Cloud service account with');
+        console.error('domain-wide delegation to access Gmail on behalf of users.');
+        console.error('\nRequired environment variables:');
+        console.error('  GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL: Service account email address');
+        console.error('    Example: my-service-account@my-project.iam.gserviceaccount.com');
+        console.error('  GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY: Service account private key (PEM format)');
+        console.error('    Example: -----BEGIN PRIVATE KEY-----\\nMIIE...\\n-----END PRIVATE KEY-----');
+        console.error('  GMAIL_IMPERSONATE_EMAIL: Email address to impersonate');
+        console.error('    Example: user@yourdomain.com');
+        console.error('\nSetup steps:');
+        console.error('  1. Go to https://console.cloud.google.com/');
+        console.error('  2. Create a service account with domain-wide delegation');
+        console.error('  3. In Google Workspace Admin, grant gmail.readonly scope');
+        console.error('  4. Download the JSON key file and extract client_email and private_key');
+        console.error('\n======================================================\n');
+        process.exit(1);
+    }
+}
+// =============================================================================
+// MAIN ENTRY POINT
+// =============================================================================
+async function main() {
+    // Step 1: Validate environment variables
+    validateEnvironment();
+    // Step 2: Create server using factory
+    const { server, registerHandlers } = createMCPServer();
+    // Step 3: Register all handlers (tools)
+    await registerHandlers(server);
+    // Step 4: Start server with stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logServerStart('Gmail');
+}
+// Run the server
+main().catch((error) => {
+    logError('main', error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "gmail-workspace-mcp-server",
+  "version": "0.0.3",
+  "description": "MCP server for Gmail integration with service account support",
+  "main": "build/index.js",
+  "type": "module",
+  "bin": {
+    "gmail-workspace-mcp-server": "./build/index.js"
+  },
+  "files": [
+    "build/**/*.js",
+    "build/**/*.d.ts",
+    "shared/**/*.js",
+    "shared/**/*.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && npm run build:integration",
+    "build:integration": "tsc -p tsconfig.integration.json",
+    "start": "node build/index.js",
+    "dev": "tsx src/index.ts",
+    "predev": "cd ../shared && npm run build && cd ../local && node setup-dev.js",
+    "prebuild": "cd ../shared && npm run build && cd ../local && node setup-dev.js",
+    "prepublishOnly": "node prepare-publish.js && node ../scripts/prepare-npm-readme.js",
+    "lint": "eslint . --ext .ts,.tsx",
+    "lint:fix": "eslint . --ext .ts,.tsx --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "stage-publish": "npm version"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.19.1",
+    "google-auth-library": "^10.5.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.6",
+    "tsx": "^4.19.4",
+    "typescript": "^5.7.3"
+  },
+  "keywords": [
+    "mcp",
+    "gmail",
+    "model-context-protocol"
+  ],
+  "author": "PulseMCP",
+  "license": "MIT"
+}

package/shared/gmail-client/lib/api-errors.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Handles Gmail API errors with structured error messages
+ * @param status HTTP status code
+ * @param operation Description of the operation that failed
+ * @param resourceId Optional resource identifier (e.g., message ID)
+ */
+export declare function handleApiError(status: number, operation: string, resourceId?: string): never;

package/shared/gmail-client/lib/api-errors.js

@@ -0,0 +1,21 @@
+/**
+ * Handles Gmail API errors with structured error messages
+ * @param status HTTP status code
+ * @param operation Description of the operation that failed
+ * @param resourceId Optional resource identifier (e.g., message ID)
+ */
+export function handleApiError(status, operation, resourceId) {
+    if (status === 401) {
+        throw new Error('Service account authentication failed. Verify the key file and domain-wide delegation.');
+    }
+    if (status === 403) {
+        throw new Error('Permission denied. Ensure gmail.readonly scope is granted in Google Workspace Admin.');
+    }
+    if (status === 429) {
+        throw new Error('Gmail API rate limit exceeded. Please try again later.');
+    }
+    if (status === 404) {
+        throw new Error(resourceId ? `Resource not found: ${resourceId}` : 'Gmail resource not found.');
+    }
+    throw new Error(`Gmail API error while ${operation}: HTTP ${status}`);
+}

package/shared/gmail-client/lib/get-message.d.ts

@@ -0,0 +1,9 @@
+import type { Email } from '../../types.js';
+/**
+ * Gets a specific message by ID
+ * Supports different format levels for detail control
+ */
+export declare function getMessage(baseUrl: string, headers: Record<string, string>, messageId: string, options?: {
+    format?: 'minimal' | 'full' | 'raw' | 'metadata';
+    metadataHeaders?: string[];
+}): Promise<Email>;

package/shared/gmail-client/lib/get-message.js

@@ -0,0 +1,24 @@
+import { handleApiError } from './api-errors.js';
+/**
+ * Gets a specific message by ID
+ * Supports different format levels for detail control
+ */
+export async function getMessage(baseUrl, headers, messageId, options) {
+    const params = new URLSearchParams();
+    if (options?.format) {
+        params.set('format', options.format);
+    }
+    if (options?.metadataHeaders && options.metadataHeaders.length > 0) {
+        options.metadataHeaders.forEach((header) => params.append('metadataHeaders', header));
+    }
+    const queryString = params.toString();
+    const url = `${baseUrl}/messages/${messageId}${queryString ? `?${queryString}` : ''}`;
+    const response = await fetch(url, {
+        method: 'GET',
+        headers,
+    });
+    if (!response.ok) {
+        handleApiError(response.status, 'getting message', messageId);
+    }
+    return (await response.json());
+}

package/shared/gmail-client/lib/list-messages.d.ts

@@ -0,0 +1,15 @@
+import type { EmailListItem } from '../../types.js';
+/**
+ * Lists messages matching a query
+ * Uses pagination to fetch results
+ */
+export declare function listMessages(baseUrl: string, headers: Record<string, string>, options?: {
+    q?: string;
+    maxResults?: number;
+    pageToken?: string;
+    labelIds?: string[];
+}): Promise<{
+    messages: EmailListItem[];
+    nextPageToken?: string;
+    resultSizeEstimate?: number;
+}>;

package/shared/gmail-client/lib/list-messages.js

@@ -0,0 +1,35 @@
+import { handleApiError } from './api-errors.js';
+/**
+ * Lists messages matching a query
+ * Uses pagination to fetch results
+ */
+export async function listMessages(baseUrl, headers, options) {
+    const params = new URLSearchParams();
+    if (options?.q) {
+        params.set('q', options.q);
+    }
+    if (options?.maxResults) {
+        params.set('maxResults', options.maxResults.toString());
+    }
+    if (options?.pageToken) {
+        params.set('pageToken', options.pageToken);
+    }
+    if (options?.labelIds && options.labelIds.length > 0) {
+        options.labelIds.forEach((labelId) => params.append('labelIds', labelId));
+    }
+    const queryString = params.toString();
+    const url = `${baseUrl}/messages${queryString ? `?${queryString}` : ''}`;
+    const response = await fetch(url, {
+        method: 'GET',
+        headers,
+    });
+    if (!response.ok) {
+        handleApiError(response.status, 'listing messages');
+    }
+    const data = (await response.json());
+    return {
+        messages: data.messages ?? [],
+        nextPageToken: data.nextPageToken,
+        resultSizeEstimate: data.resultSizeEstimate,
+    };
+}

package/shared/index.d.ts

@@ -0,0 +1,4 @@
+export { createMCPServer, createDefaultClient, ServiceAccountGmailClient, type IGmailClient, type ClientFactory, type ServiceAccountCredentials, } from './server.js';
+export { createRegisterTools, registerTools } from './tools.js';
+export { logServerStart, logError, logWarning, logDebug } from './logging.js';
+export type { Email, EmailListItem, EmailHeader, EmailPart, Label, Thread, PaginatedResponse, } from './types.js';

package/shared/index.js

@@ -0,0 +1,7 @@
+// Main exports for Gmail MCP Server
+// Server and client
+export { createMCPServer, createDefaultClient, ServiceAccountGmailClient, } from './server.js';
+// Tools
+export { createRegisterTools, registerTools } from './tools.js';
+// Logging utilities
+export { logServerStart, logError, logWarning, logDebug } from './logging.js';

package/shared/logging.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Centralized logging utilities for Gmail MCP Server
+ *
+ * IMPORTANT: All logging uses console.error() to write to stderr.
+ * The MCP protocol requires stdout to contain only JSON messages.
+ */
+export declare function logServerStart(serverName: string, transport?: string): void;
+export declare function logError(context: string, error: unknown): void;
+export declare function logWarning(context: string, message: string): void;
+export declare function logDebug(context: string, message: string): void;

package/shared/logging.js

@@ -0,0 +1,21 @@
+/**
+ * Centralized logging utilities for Gmail MCP Server
+ *
+ * IMPORTANT: All logging uses console.error() to write to stderr.
+ * The MCP protocol requires stdout to contain only JSON messages.
+ */
+export function logServerStart(serverName, transport = 'stdio') {
+    console.error(`MCP server ${serverName} running on ${transport}`);
+}
+export function logError(context, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[ERROR] ${context}: ${message}`);
+}
+export function logWarning(context, message) {
+    console.error(`[WARN] ${context}: ${message}`);
+}
+export function logDebug(context, message) {
+    if (process.env.NODE_ENV === 'development' || process.env.DEBUG) {
+        console.error(`[DEBUG] ${context}: ${message}`);
+    }
+}

package/shared/server.d.ts

@@ -0,0 +1,117 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { Email, EmailListItem } from './types.js';
+/**
+ * Gmail API client interface
+ * Defines all methods for interacting with the Gmail API
+ */
+export interface IGmailClient {
+    /**
+     * List messages matching a query
+     */
+    listMessages(options?: {
+        q?: string;
+        maxResults?: number;
+        pageToken?: string;
+        labelIds?: string[];
+    }): Promise<{
+        messages: EmailListItem[];
+        nextPageToken?: string;
+        resultSizeEstimate?: number;
+    }>;
+    /**
+     * Get a specific message by ID
+     */
+    getMessage(messageId: string, options?: {
+        format?: 'minimal' | 'full' | 'raw' | 'metadata';
+        metadataHeaders?: string[];
+    }): Promise<Email>;
+}
+/**
+ * Service account credentials structure
+ */
+export interface ServiceAccountCredentials {
+    type: string;
+    project_id: string;
+    private_key_id: string;
+    private_key: string;
+    client_email: string;
+    client_id: string;
+    auth_uri: string;
+    token_uri: string;
+    auth_provider_x509_cert_url: string;
+    client_x509_cert_url: string;
+}
+/**
+ * Gmail API client implementation using service account with domain-wide delegation
+ */
+export declare class ServiceAccountGmailClient implements IGmailClient {
+    private impersonateEmail;
+    private baseUrl;
+    private jwtClient;
+    private cachedToken;
+    private tokenExpiry;
+    private refreshPromise;
+    constructor(credentials: ServiceAccountCredentials, impersonateEmail: string);
+    private refreshToken;
+    private getHeaders;
+    listMessages(options?: {
+        q?: string;
+        maxResults?: number;
+        pageToken?: string;
+        labelIds?: string[];
+    }): Promise<{
+        messages: EmailListItem[];
+        nextPageToken?: string;
+        resultSizeEstimate?: number;
+    }>;
+    getMessage(messageId: string, options?: {
+        format?: 'minimal' | 'full' | 'raw' | 'metadata';
+        metadataHeaders?: string[];
+    }): Promise<Email>;
+}
+export type ClientFactory = () => IGmailClient;
+/**
+ * Creates the default Gmail client based on environment variables.
+ * Uses service account with domain-wide delegation:
+ *   - GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL: Service account email address
+ *   - GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY: Service account private key (PEM format)
+ *   - GMAIL_IMPERSONATE_EMAIL: Email address to impersonate
+ */
+export declare function createDefaultClient(): IGmailClient;
+export declare function createMCPServer(): {
+    server: Server<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    registerHandlers: (server: Server, clientFactory?: ClientFactory) => Promise<void>;
+};

package/shared/server.js

@@ -0,0 +1,117 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { JWT } from 'google-auth-library';
+import { createRegisterTools } from './tools.js';
+/**
+ * Gmail API client implementation using service account with domain-wide delegation
+ */
+export class ServiceAccountGmailClient {
+    impersonateEmail;
+    baseUrl = 'https://gmail.googleapis.com/gmail/v1/users/me';
+    jwtClient;
+    cachedToken = null;
+    tokenExpiry = 0;
+    refreshPromise = null;
+    constructor(credentials, impersonateEmail) {
+        this.impersonateEmail = impersonateEmail;
+        this.jwtClient = new JWT({
+            email: credentials.client_email,
+            key: credentials.private_key,
+            scopes: ['https://www.googleapis.com/auth/gmail.readonly'],
+            subject: impersonateEmail,
+        });
+    }
+    async refreshToken() {
+        const tokenResponse = await this.jwtClient.authorize();
+        if (!tokenResponse.access_token) {
+            throw new Error('Failed to obtain access token from service account');
+        }
+        this.cachedToken = tokenResponse.access_token;
+        // Token typically expires in 1 hour, but use the actual expiry if provided
+        this.tokenExpiry = tokenResponse.expiry_date || Date.now() + 3600000;
+    }
+    async getHeaders() {
+        // Check if we have a valid cached token (with 60 second buffer)
+        if (this.cachedToken && Date.now() < this.tokenExpiry - 60000) {
+            return {
+                Authorization: `Bearer ${this.cachedToken}`,
+                'Content-Type': 'application/json',
+            };
+        }
+        // Use mutex pattern to prevent concurrent token refresh
+        if (!this.refreshPromise) {
+            this.refreshPromise = this.refreshToken().finally(() => {
+                this.refreshPromise = null;
+            });
+        }
+        await this.refreshPromise;
+        return {
+            Authorization: `Bearer ${this.cachedToken}`,
+            'Content-Type': 'application/json',
+        };
+    }
+    async listMessages(options) {
+        const headers = await this.getHeaders();
+        const { listMessages } = await import('./gmail-client/lib/list-messages.js');
+        return listMessages(this.baseUrl, headers, options);
+    }
+    async getMessage(messageId, options) {
+        const headers = await this.getHeaders();
+        const { getMessage } = await import('./gmail-client/lib/get-message.js');
+        return getMessage(this.baseUrl, headers, messageId, options);
+    }
+}
+/**
+ * Creates the default Gmail client based on environment variables.
+ * Uses service account with domain-wide delegation:
+ *   - GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL: Service account email address
+ *   - GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY: Service account private key (PEM format)
+ *   - GMAIL_IMPERSONATE_EMAIL: Email address to impersonate
+ */
+export function createDefaultClient() {
+    const clientEmail = process.env.GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL;
+    // Handle both literal \n in JSON configs and actual newlines
+    const privateKey = process.env.GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY?.replace(/\\n/g, '\n');
+    const impersonateEmail = process.env.GMAIL_IMPERSONATE_EMAIL;
+    if (!clientEmail) {
+        throw new Error('GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL environment variable must be set. ' +
+            'This is the email address from your Google Cloud service account.');
+    }
+    if (!privateKey) {
+        throw new Error('GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY environment variable must be set. ' +
+            'This is the private key from your Google Cloud service account (PEM format).');
+    }
+    if (!impersonateEmail) {
+        throw new Error('GMAIL_IMPERSONATE_EMAIL environment variable must be set. ' +
+            'This is the email address of the user to access Gmail as.');
+    }
+    const credentials = {
+        type: 'service_account',
+        project_id: '',
+        private_key_id: '',
+        private_key: privateKey,
+        client_email: clientEmail,
+        client_id: '',
+        auth_uri: 'https://accounts.google.com/o/oauth2/auth',
+        token_uri: 'https://oauth2.googleapis.com/token',
+        auth_provider_x509_cert_url: 'https://www.googleapis.com/oauth2/v1/certs',
+        client_x509_cert_url: '',
+    };
+    return new ServiceAccountGmailClient(credentials, impersonateEmail);
+}
+export function createMCPServer() {
+    const server = new Server({
+        name: 'gmail-workspace-mcp-server',
+        version: '0.0.2',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    const registerHandlers = async (server, clientFactory) => {
+        // Use provided factory or create default client
+        const factory = clientFactory || createDefaultClient;
+        const registerTools = createRegisterTools(factory);
+        registerTools(server);
+    };
+    return { server, registerHandlers };
+}

package/shared/tools/get-email.d.ts

@@ -0,0 +1,37 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { ClientFactory } from '../server.js';
+export declare const GetEmailSchema: z.ZodObject<{
+    email_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    email_id: string;
+}, {
+    email_id: string;
+}>;
+export declare function getEmailTool(server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            email_id: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};

package/shared/tools/get-email.js

@@ -0,0 +1,192 @@
+import { z } from 'zod';
+import { getHeader } from '../utils/email-helpers.js';
+const PARAM_DESCRIPTIONS = {
+    email_id: 'The unique identifier of the email to retrieve. ' +
+        'Obtain this from gmail_list_recent_emails.',
+};
+export const GetEmailSchema = z.object({
+    email_id: z.string().min(1).describe(PARAM_DESCRIPTIONS.email_id),
+});
+const TOOL_DESCRIPTION = `Retrieve the full content of a specific email by its ID.
+
+Returns the complete email including headers, body content, and attachment information.
+
+**Parameters:**
+- email_id: The unique identifier of the email (required)
+
+**Returns:**
+Full email details including:
+- Subject, From, To, Cc, Date headers
+- Full message body (plain text preferred, HTML as fallback)
+- List of attachments (if any)
+- Labels assigned to the email
+
+**Use cases:**
+- Read the full content of an email after listing recent emails
+- Extract specific information from an email body
+- Check attachment details
+
+**Note:** Use gmail_list_recent_emails first to get email IDs.`;
+/**
+ * Decodes base64url encoded content
+ */
+function decodeBase64Url(data) {
+    // Convert base64url to base64
+    const base64 = data.replace(/-/g, '+').replace(/_/g, '/');
+    // Decode from base64
+    return Buffer.from(base64, 'base64').toString('utf-8');
+}
+/**
+ * Recursively extracts body content from email parts
+ * Prefers text/plain over text/html
+ */
+function extractBodyContent(parts, preferredType = 'text/plain') {
+    if (!parts)
+        return null;
+    // First pass: look for exact match
+    for (const part of parts) {
+        if (part.mimeType === preferredType && part.body?.data) {
+            return decodeBase64Url(part.body.data);
+        }
+        if (part.parts) {
+            const nested = extractBodyContent(part.parts, preferredType);
+            if (nested)
+                return nested;
+        }
+    }
+    return null;
+}
+/**
+ * Gets the body content from an email
+ */
+function getEmailBody(email) {
+    // Check if body is directly on payload
+    if (email.payload?.body?.data) {
+        return decodeBase64Url(email.payload.body.data);
+    }
+    // Try to extract from parts
+    if (email.payload?.parts) {
+        // Prefer plain text
+        const plainText = extractBodyContent(email.payload.parts, 'text/plain');
+        if (plainText)
+            return plainText;
+        // Fall back to HTML
+        const html = extractBodyContent(email.payload.parts, 'text/html');
+        if (html) {
+            // Strip HTML tags for readability
+            return html
+                .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
+                .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
+                .replace(/<[^>]+>/g, ' ')
+                .replace(/\s+/g, ' ')
+                .trim();
+        }
+    }
+    return '(No body content available)';
+}
+/**
+ * Extracts attachment information from email parts
+ */
+function getAttachments(parts) {
+    if (!parts)
+        return [];
+    const attachments = [];
+    for (const part of parts) {
+        if (part.filename && part.body?.attachmentId) {
+            attachments.push({
+                filename: part.filename,
+                mimeType: part.mimeType,
+                size: part.body.size,
+            });
+        }
+        if (part.parts) {
+            attachments.push(...getAttachments(part.parts));
+        }
+    }
+    return attachments;
+}
+/**
+ * Formats an email for display
+ */
+function formatFullEmail(email) {
+    const subject = getHeader(email, 'Subject') || '(No Subject)';
+    const from = getHeader(email, 'From') || 'Unknown';
+    const to = getHeader(email, 'To') || 'Unknown';
+    const cc = getHeader(email, 'Cc');
+    const date = getHeader(email, 'Date') || 'Unknown date';
+    const body = getEmailBody(email);
+    const attachments = getAttachments(email.payload?.parts);
+    const labels = email.labelIds?.join(', ') || 'None';
+    let output = `# Email Details
+
+**ID:** ${email.id}
+**Thread ID:** ${email.threadId}
+
+## Headers
+**Subject:** ${subject}
+**From:** ${from}
+**To:** ${to}`;
+    if (cc) {
+        output += `\n**Cc:** ${cc}`;
+    }
+    output += `
+**Date:** ${date}
+**Labels:** ${labels}
+
+## Body
+
+${body}`;
+    if (attachments.length > 0) {
+        output += `\n\n## Attachments (${attachments.length})\n`;
+        attachments.forEach((att, i) => {
+            const sizeKb = Math.round(att.size / 1024);
+            output += `${i + 1}. ${att.filename} (${att.mimeType}, ${sizeKb} KB)\n`;
+        });
+    }
+    return output;
+}
+export function getEmailTool(server, clientFactory) {
+    return {
+        name: 'gmail_get_email',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                email_id: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.email_id,
+                },
+            },
+            required: ['email_id'],
+        },
+        handler: async (args) => {
+            try {
+                const parsed = GetEmailSchema.parse(args ?? {});
+                const client = clientFactory();
+                const email = await client.getMessage(parsed.email_id, {
+                    format: 'full',
+                });
+                const formattedEmail = formatFullEmail(email);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: formattedEmail,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error retrieving email: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/list-recent-emails.d.ts

@@ -0,0 +1,54 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { ClientFactory } from '../server.js';
+export declare const ListRecentEmailsSchema: z.ZodObject<{
+    hours: z.ZodDefault<z.ZodNumber>;
+    labels: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    max_results: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    hours: number;
+    labels: string;
+    max_results: number;
+}, {
+    hours?: number | undefined;
+    labels?: string | undefined;
+    max_results?: number | undefined;
+}>;
+export declare function listRecentEmailsTool(server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            hours: {
+                type: string;
+                default: number;
+                description: string;
+            };
+            labels: {
+                type: string;
+                default: string;
+                description: string;
+            };
+            max_results: {
+                type: string;
+                default: number;
+                description: "Maximum number of emails to return. Default: 10. Max: 100.";
+            };
+        };
+        required: never[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};

package/shared/tools/list-recent-emails.js

@@ -0,0 +1,133 @@
+import { z } from 'zod';
+import { getHeader } from '../utils/email-helpers.js';
+const PARAM_DESCRIPTIONS = {
+    hours: 'Time horizon in hours to look back for emails. Default: 24. ' +
+        'Example: 48 for the last 2 days.',
+    labels: 'Comma-separated list of label IDs to filter by. Default: INBOX. ' +
+        'Common labels: INBOX, SENT, DRAFTS, SPAM, TRASH, STARRED, IMPORTANT, UNREAD.',
+    max_results: 'Maximum number of emails to return. Default: 10. Max: 100.',
+};
+export const ListRecentEmailsSchema = z.object({
+    hours: z.number().positive().default(24).describe(PARAM_DESCRIPTIONS.hours),
+    labels: z.string().optional().default('INBOX').describe(PARAM_DESCRIPTIONS.labels),
+    max_results: z.number().positive().max(100).default(10).describe(PARAM_DESCRIPTIONS.max_results),
+});
+const TOOL_DESCRIPTION = `List recent emails from Gmail within a specified time horizon.
+
+Returns a list of recent emails with their subject, sender, date, and a snippet preview. Use get_email to retrieve the full content of a specific email.
+
+**Parameters:**
+- hours: How far back to look for emails (default: 24 hours)
+- labels: Which labels/folders to search (default: INBOX)
+- max_results: Maximum emails to return (default: 10, max: 100)
+
+**Returns:**
+A formatted list of emails with:
+- Email ID (needed for get_email)
+- Subject line
+- Sender (From)
+- Date received
+- Snippet preview
+
+**Use cases:**
+- Check recent inbox activity
+- Monitor for new emails in a time window
+- List recent emails from specific labels like SENT or STARRED
+
+**Note:** This tool only returns email metadata and snippets. Use get_email with an email ID to retrieve the full message content.`;
+/**
+ * Formats an email for display
+ */
+function formatEmail(email) {
+    const subject = getHeader(email, 'Subject') || '(No Subject)';
+    const from = getHeader(email, 'From') || 'Unknown';
+    const date = getHeader(email, 'Date') || 'Unknown date';
+    const snippet = email.snippet || '';
+    return `**ID:** ${email.id}
+**Subject:** ${subject}
+**From:** ${from}
+**Date:** ${date}
+**Preview:** ${snippet}`;
+}
+export function listRecentEmailsTool(server, clientFactory) {
+    return {
+        name: 'gmail_list_recent_emails',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                hours: {
+                    type: 'number',
+                    default: 24,
+                    description: PARAM_DESCRIPTIONS.hours,
+                },
+                labels: {
+                    type: 'string',
+                    default: 'INBOX',
+                    description: PARAM_DESCRIPTIONS.labels,
+                },
+                max_results: {
+                    type: 'number',
+                    default: 10,
+                    description: PARAM_DESCRIPTIONS.max_results,
+                },
+            },
+            required: [],
+        },
+        handler: async (args) => {
+            try {
+                const parsed = ListRecentEmailsSchema.parse(args ?? {});
+                const client = clientFactory();
+                // Calculate the timestamp for the time horizon
+                const now = new Date();
+                const cutoffDate = new Date(now.getTime() - parsed.hours * 60 * 60 * 1000);
+                const afterTimestamp = Math.floor(cutoffDate.getTime() / 1000);
+                // Build the Gmail query
+                const query = `after:${afterTimestamp}`;
+                // Parse labels
+                const labelIds = parsed.labels.split(',').map((l) => l.trim().toUpperCase());
+                // List messages
+                const { messages } = await client.listMessages({
+                    q: query,
+                    maxResults: parsed.max_results,
+                    labelIds,
+                });
+                if (messages.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `No emails found in the last ${parsed.hours} hour(s) with labels: ${labelIds.join(', ')}`,
+                            },
+                        ],
+                    };
+                }
+                // Fetch full details for each message
+                const emailDetails = await Promise.all(messages.map((msg) => client.getMessage(msg.id, {
+                    format: 'metadata',
+                    metadataHeaders: ['Subject', 'From', 'Date'],
+                })));
+                const formattedEmails = emailDetails.map(formatEmail).join('\n\n---\n\n');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Found ${messages.length} email(s) in the last ${parsed.hours} hour(s):\n\n${formattedEmails}`,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error listing emails: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools.d.ts

@@ -0,0 +1,10 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { ClientFactory } from './server.js';
+/**
+ * Creates a function to register all tools with the server
+ */
+export declare function createRegisterTools(clientFactory: ClientFactory): (server: Server) => void;
+/**
+ * Backward compatibility export
+ */
+export declare function registerTools(server: Server): void;

package/shared/tools.js

@@ -0,0 +1,45 @@
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { listRecentEmailsTool } from './tools/list-recent-emails.js';
+import { getEmailTool } from './tools/get-email.js';
+/**
+ * All available tools
+ */
+const ALL_TOOLS = [listRecentEmailsTool, getEmailTool];
+/**
+ * Creates a function to register all tools with the server
+ */
+export function createRegisterTools(clientFactory) {
+    return (server) => {
+        // Create tool instances
+        const tools = ALL_TOOLS.map((factory) => factory(server, clientFactory));
+        // List available tools
+        server.setRequestHandler(ListToolsRequestSchema, async () => {
+            return {
+                tools: tools.map((tool) => ({
+                    name: tool.name,
+                    description: tool.description,
+                    inputSchema: tool.inputSchema,
+                })),
+            };
+        });
+        // Handle tool calls
+        server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            const tool = tools.find((t) => t.name === name);
+            if (!tool) {
+                throw new Error(`Unknown tool: ${name}`);
+            }
+            return await tool.handler(args);
+        });
+    };
+}
+/**
+ * Backward compatibility export
+ */
+export function registerTools(server) {
+    const factory = () => {
+        throw new Error('No client factory provided - use createRegisterTools for dependency injection');
+    };
+    const register = createRegisterTools(factory);
+    register(server);
+}

package/shared/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Gmail API Types
+ * Based on Gmail API responses
+ */
+export interface EmailHeader {
+    name: string;
+    value: string;
+}
+export interface EmailPart {
+    partId: string;
+    mimeType: string;
+    filename?: string;
+    headers?: EmailHeader[];
+    body?: {
+        attachmentId?: string;
+        size: number;
+        data?: string;
+    };
+    parts?: EmailPart[];
+}
+export interface Email {
+    id: string;
+    threadId: string;
+    labelIds?: string[];
+    snippet: string;
+    historyId: string;
+    internalDate: string;
+    payload?: {
+        partId?: string;
+        mimeType: string;
+        filename?: string;
+        headers?: EmailHeader[];
+        body?: {
+            attachmentId?: string;
+            size: number;
+            data?: string;
+        };
+        parts?: EmailPart[];
+    };
+    sizeEstimate?: number;
+}
+export interface EmailListItem {
+    id: string;
+    threadId: string;
+}
+export interface Label {
+    id: string;
+    name: string;
+    messageListVisibility?: 'show' | 'hide';
+    labelListVisibility?: 'labelShow' | 'labelShowIfUnread' | 'labelHide';
+    type?: 'system' | 'user';
+    color?: {
+        textColor: string;
+        backgroundColor: string;
+    };
+}
+export interface Thread {
+    id: string;
+    historyId: string;
+    messages?: Email[];
+}
+export interface PaginatedResponse<T> {
+    items: T[];
+    nextPageToken?: string;
+    resultSizeEstimate?: number;
+}

package/shared/types.js

@@ -0,0 +1,5 @@
+/**
+ * Gmail API Types
+ * Based on Gmail API responses
+ */
+export {};

package/shared/utils/email-helpers.d.ts

@@ -0,0 +1,5 @@
+import type { Email } from '../types.js';
+/**
+ * Extracts a header value from an email by header name (case-insensitive)
+ */
+export declare function getHeader(email: Email, headerName: string): string | undefined;

package/shared/utils/email-helpers.js

@@ -0,0 +1,7 @@
+/**
+ * Extracts a header value from an email by header name (case-insensitive)
+ */
+export function getHeader(email, headerName) {
+    return email.payload?.headers?.find((h) => h.name.toLowerCase() === headerName.toLowerCase())
+        ?.value;
+}