@node2flow/gmail-mcp 1.0.0

package/Dockerfile

@@ -0,0 +1,10 @@
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY src/ ./src/
+COPY tsconfig.json ./
+RUN npm run build
+RUN npm prune --omit=dev
+EXPOSE 3000
+CMD ["node", "dist/index.js", "--http"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Node2Flow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# @node2flow/gmail-mcp
+
+[![smithery badge](https://smithery.ai/badge/node2flow/gmail)](https://smithery.ai/server/node2flow/gmail)
+[![npm version](https://img.shields.io/npm/v/@node2flow/gmail-mcp.svg)](https://www.npmjs.com/package/@node2flow/gmail-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+MCP server for **Gmail** — send, search, read, organize emails and manage labels through 28 tools via the Model Context Protocol.
+
+## Quick Start
+
+### Claude Desktop / Cursor
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "gmail": {
+      "command": "npx",
+      "args": ["-y", "@node2flow/gmail-mcp"],
+      "env": {
+        "GOOGLE_CLIENT_ID": "your-client-id",
+        "GOOGLE_CLIENT_SECRET": "your-client-secret",
+        "GOOGLE_REFRESH_TOKEN": "your-refresh-token"
+      }
+    }
+  }
+}
+```
+
+### HTTP Mode
+
+```bash
+GOOGLE_CLIENT_ID=xxx GOOGLE_CLIENT_SECRET=xxx GOOGLE_REFRESH_TOKEN=xxx npx @node2flow/gmail-mcp --http
+```
+
+MCP endpoint: `http://localhost:3000/mcp`
+
+### Cloudflare Worker
+
+Available at: `https://gmail-mcp-community.node2flow.net/mcp`
+
+```
+POST https://gmail-mcp-community.node2flow.net/mcp?GOOGLE_CLIENT_ID=xxx&GOOGLE_CLIENT_SECRET=xxx&GOOGLE_REFRESH_TOKEN=xxx
+```
+
+---
+
+## Tools (28)
+
+### Messages (10)
+
+| Tool | Description |
+|------|-------------|
+| `gmail_list_messages` | List messages with Gmail search syntax |
+| `gmail_get_message` | Get message content (full/metadata/minimal/raw) |
+| `gmail_send_message` | Send email with to, cc, bcc, subject, body, HTML |
+| `gmail_delete_message` | Permanently delete a message |
+| `gmail_trash_message` | Move message to trash |
+| `gmail_untrash_message` | Remove message from trash |
+| `gmail_modify_message` | Add/remove labels on a message |
+| `gmail_batch_delete` | Delete multiple messages (up to 1000) |
+| `gmail_batch_modify` | Modify labels on multiple messages |
+| `gmail_get_attachment` | Get attachment data (base64) |
+
+### Drafts (6)
+
+| Tool | Description |
+|------|-------------|
+| `gmail_list_drafts` | List all drafts |
+| `gmail_get_draft` | Get draft content |
+| `gmail_create_draft` | Create a new draft |
+| `gmail_update_draft` | Update an existing draft |
+| `gmail_delete_draft` | Delete a draft |
+| `gmail_send_draft` | Send an existing draft |
+
+### Labels (5)
+
+| Tool | Description |
+|------|-------------|
+| `gmail_list_labels` | List all labels (system + user) |
+| `gmail_get_label` | Get label details with counts |
+| `gmail_create_label` | Create a new label with color |
+| `gmail_update_label` | Update label name/visibility/color |
+| `gmail_delete_label` | Delete a user-created label |
+
+### Threads (5)
+
+| Tool | Description |
+|------|-------------|
+| `gmail_list_threads` | List threads with search query |
+| `gmail_get_thread` | Get all messages in a thread |
+| `gmail_modify_thread` | Add/remove labels on a thread |
+| `gmail_trash_thread` | Move thread to trash |
+| `gmail_untrash_thread` | Remove thread from trash |
+
+### Settings (2)
+
+| Tool | Description |
+|------|-------------|
+| `gmail_get_profile` | Get email address, message/thread counts |
+| `gmail_update_vacation` | Enable/disable vacation auto-reply |
+
+---
+
+## Search Query Syntax
+
+The `q` parameter in `gmail_list_messages` and `gmail_list_threads` supports Gmail search operators:
+
+```
+from:user@example.com          — Messages from a sender
+to:user@example.com            — Messages to a recipient
+subject:"meeting notes"        — Subject contains text
+has:attachment                  — Has attachments
+filename:pdf                   — Attachment by type
+is:unread / is:starred         — Message state
+label:custom-label             — By label
+after:2026/01/01               — After date
+newer_than:2d / older_than:1y  — Relative date
+in:inbox / in:sent / in:trash  — By location
+```
+
+Combine operators: `from:boss@company.com has:attachment is:unread after:2026/01/01`
+
+---
+
+## Configuration
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `GOOGLE_CLIENT_ID` | Yes | OAuth 2.0 Client ID from Google Cloud Console |
+| `GOOGLE_CLIENT_SECRET` | Yes | OAuth 2.0 Client Secret |
+| `GOOGLE_REFRESH_TOKEN` | Yes | Refresh token (obtained via OAuth consent flow) |
+
+### Getting Your Credentials
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a project → Enable **Gmail API**
+3. Create **OAuth 2.0 Client ID** (Desktop app type)
+4. Use the [OAuth Playground](https://developers.google.com/oauthplayground/) or your app to get a refresh token with the Gmail scope
+
+### OAuth Scopes
+
+| Scope | Access |
+|-------|--------|
+| `gmail.modify` | Read, send, delete, and manage (recommended) |
+| `gmail.readonly` | Read-only access |
+| `gmail.send` | Send only |
+| `gmail.compose` | Create and send drafts |
+| `gmail.labels` | Manage labels only |
+| `mail.google.com` | Full access including permanent delete |
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE)
+
+Copyright (c) 2026 [Node2Flow](https://node2flow.net)
+
+## Links
+
+- [npm Package](https://www.npmjs.com/package/@node2flow/gmail-mcp)
+- [Gmail API](https://developers.google.com/gmail/api)
+- [MCP Protocol](https://modelcontextprotocol.io/)
+- [Node2Flow](https://node2flow.net)

package/dist/gmail-client.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Gmail API v1 Client — OAuth 2.0 refresh token pattern
+ */
+import type { Message, MessageList, Thread, ThreadList, Label, LabelList, Draft, DraftList, Profile, VacationSettings, Attachment } from './types.js';
+export interface GmailClientConfig {
+    clientId: string;
+    clientSecret: string;
+    refreshToken: string;
+}
+export declare class GmailClient {
+    private config;
+    private accessToken;
+    private tokenExpiry;
+    private static readonly BASE;
+    private static readonly TOKEN_URL;
+    constructor(config: GmailClientConfig);
+    private getAccessToken;
+    private request;
+    private buildRawMessage;
+    private base64Encode;
+    private base64UrlEncode;
+    listMessages(opts: {
+        q?: string;
+        labelIds?: string[];
+        maxResults?: number;
+        pageToken?: string;
+        includeSpamTrash?: boolean;
+    }): Promise<MessageList>;
+    getMessage(opts: {
+        id: string;
+        format?: string;
+        metadataHeaders?: string[];
+    }): Promise<Message>;
+    sendMessage(opts: {
+        to: string;
+        subject: string;
+        body: string;
+        cc?: string;
+        bcc?: string;
+        html?: string;
+        in_reply_to?: string;
+        references?: string;
+        thread_id?: string;
+    }): Promise<Message>;
+    deleteMessage(opts: {
+        id: string;
+    }): Promise<void>;
+    trashMessage(opts: {
+        id: string;
+    }): Promise<Message>;
+    untrashMessage(opts: {
+        id: string;
+    }): Promise<Message>;
+    modifyMessage(opts: {
+        id: string;
+        addLabelIds?: string[];
+        removeLabelIds?: string[];
+    }): Promise<Message>;
+    batchDeleteMessages(opts: {
+        ids: string[];
+    }): Promise<void>;
+    batchModifyMessages(opts: {
+        ids: string[];
+        addLabelIds?: string[];
+        removeLabelIds?: string[];
+    }): Promise<void>;
+    getAttachment(opts: {
+        messageId: string;
+        attachmentId: string;
+    }): Promise<Attachment>;
+    listDrafts(opts: {
+        maxResults?: number;
+        pageToken?: string;
+        q?: string;
+    }): Promise<DraftList>;
+    getDraft(opts: {
+        id: string;
+        format?: string;
+    }): Promise<Draft>;
+    createDraft(opts: {
+        to: string;
+        subject: string;
+        body: string;
+        cc?: string;
+        bcc?: string;
+        html?: string;
+        thread_id?: string;
+    }): Promise<Draft>;
+    updateDraft(opts: {
+        id: string;
+        to: string;
+        subject: string;
+        body: string;
+        cc?: string;
+        bcc?: string;
+        html?: string;
+        thread_id?: string;
+    }): Promise<Draft>;
+    deleteDraft(opts: {
+        id: string;
+    }): Promise<void>;
+    sendDraft(opts: {
+        id: string;
+    }): Promise<Message>;
+    listLabels(): Promise<LabelList>;
+    getLabel(opts: {
+        id: string;
+    }): Promise<Label>;
+    createLabel(opts: {
+        name: string;
+        messageListVisibility?: string;
+        labelListVisibility?: string;
+        backgroundColor?: string;
+        textColor?: string;
+    }): Promise<Label>;
+    updateLabel(opts: {
+        id: string;
+        name?: string;
+        messageListVisibility?: string;
+        labelListVisibility?: string;
+        backgroundColor?: string;
+        textColor?: string;
+    }): Promise<Label>;
+    deleteLabel(opts: {
+        id: string;
+    }): Promise<void>;
+    listThreads(opts: {
+        q?: string;
+        labelIds?: string[];
+        maxResults?: number;
+        pageToken?: string;
+        includeSpamTrash?: boolean;
+    }): Promise<ThreadList>;
+    getThread(opts: {
+        id: string;
+        format?: string;
+    }): Promise<Thread>;
+    modifyThread(opts: {
+        id: string;
+        addLabelIds?: string[];
+        removeLabelIds?: string[];
+    }): Promise<Thread>;
+    trashThread(opts: {
+        id: string;
+    }): Promise<Thread>;
+    untrashThread(opts: {
+        id: string;
+    }): Promise<Thread>;
+    getProfile(): Promise<Profile>;
+    updateVacation(opts: {
+        enableAutoReply: boolean;
+        responseSubject?: string;
+        responseBodyPlainText?: string;
+        responseBodyHtml?: string;
+        restrictToContacts?: boolean;
+        restrictToDomain?: boolean;
+        startTime?: string;
+        endTime?: string;
+    }): Promise<VacationSettings>;
+}
+//# sourceMappingURL=gmail-client.d.ts.map

package/dist/gmail-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gmail-client.d.ts","sourceRoot":"","sources":["../src/gmail-client.ts"],"names":[],"mappings":"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"}