@mcp-z/mcp-gmail 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kevin Malakoff
+
+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,167 @@
+# @mcp-z/mcp-gmail
+
+Docs: https://mcp-z.github.io/mcp-gmail
+Gmail MCP server for searching, reading, and sending mail over MCP.
+
+## Common uses
+
+- Search and read messages
+- Send and reply to emails
+- Manage labels and export messages to CSV
+
+## Transports
+
+MCP supports stdio and HTTP.
+
+**Stdio**
+```json
+{
+  "mcpServers": {
+    "gmail": {
+      "command": "npx",
+      "args": ["-y", "@mcp-z/mcp-gmail"]
+    }
+  }
+}
+```
+
+**HTTP**
+```json
+{
+  "mcpServers": {
+    "gmail": {
+      "type": "http",
+      "url": "http://localhost:9002/mcp",
+      "start": {
+        "command": "npx",
+        "args": ["-y", "@mcp-z/mcp-gmail", "--port=9002"]
+      }
+    }
+  }
+}
+```
+
+`start` is an extension used by `npx @mcp-z/cli up` to launch HTTP servers for you.
+
+## Create a Google Cloud app
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/).
+2. Create or select a project.
+3. Enable the Gmail API.
+4. Create OAuth 2.0 credentials (Desktop app).
+5. Copy the Client ID and Client Secret.
+
+## OAuth modes
+
+Configure via environment variables or the `env` block in `.mcp.json`. See `server.json` for the full list of options.
+
+### Loopback OAuth (default)
+
+Environment variables:
+
+```bash
+GOOGLE_CLIENT_ID=your-client-id
+GOOGLE_CLIENT_SECRET=your-client-secret
+```
+
+Example:
+```json
+{
+  "mcpServers": {
+    "gmail": {
+      "command": "npx",
+      "args": ["-y", "@mcp-z/mcp-gmail"],
+      "env": {
+        "GOOGLE_CLIENT_ID": "your-client-id",
+        "GOOGLE_CLIENT_SECRET": "your-client-secret"
+      }
+    }
+  }
+}
+```
+
+### Service account
+
+Environment variables:
+
+```bash
+AUTH_MODE=service-account
+GOOGLE_SERVICE_ACCOUNT_KEY_FILE=/path/to/service-account.json
+```
+
+Example:
+```json
+{
+  "mcpServers": {
+    "gmail": {
+      "command": "npx",
+      "args": ["-y", "@mcp-z/mcp-gmail", "--auth=service-account"],
+      "env": {
+        "GOOGLE_SERVICE_ACCOUNT_KEY_FILE": "/path/to/service-account.json"
+      }
+    }
+  }
+}
+```
+
+### DCR (self-hosted)
+
+HTTP only. Requires a public base URL.
+
+```json
+{
+  "mcpServers": {
+    "gmail-dcr": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@mcp-z/mcp-gmail",
+        "--auth=dcr",
+        "--port=3456",
+        "--base-url=https://oauth.example.com"
+      ],
+      "env": {
+        "GOOGLE_CLIENT_ID": "your-client-id",
+        "GOOGLE_CLIENT_SECRET": "your-client-secret"
+      }
+    }
+  }
+}
+```
+
+## How to use
+
+```bash
+# List tools
+mcp-z inspect --servers gmail --tools
+
+# Call a tool
+mcp-z call gmail message-search '{"query":"from:alice@example.com"}'
+```
+
+## Tools
+
+1. categories-list
+2. label-add
+3. label-delete
+4. labels-list
+5. message-get
+6. message-mark-read
+7. message-move-to-trash
+8. message-respond
+9. message-search
+10. message-send
+11. messages-export-csv
+
+## Resources
+
+1. email
+
+## Prompts
+
+1. draft-email
+2. query-syntax
+
+## Configuration reference
+
+See `server.json` for all supported environment variables, CLI arguments, and defaults.

package/bin/server.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+// biome-ignore lint/security/noGlobalEval: dual esm and cjs
+if (typeof require === 'undefined') eval("import('../dist/esm/index.js').then((cli) => cli.default(process.argv.slice(2), 'mcp-gmail')).catch((err) => { console.log(err); process.exit(-1); });");
+else require('../dist/cjs/index.js')(process.argv.slice(2), 'mcp-gmail');

package/dist/cjs/constants.d.cts

@@ -0,0 +1,11 @@
+/**
+ * Gmail MCP Server Constants
+ *
+ * These scopes are required for Gmail functionality and are hardcoded
+ * rather than externally configured since this server knows its own requirements.
+ */
+export declare const GOOGLE_SCOPE = "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email https://mail.google.com/";
+export declare const CHUNK_SIZE = 10;
+export declare const MAX_BATCH_SIZE = 500;
+export declare const DEFAULT_PAGE_SIZE = 50;
+export declare const MAX_PAGE_SIZE = 1000;

package/dist/cjs/constants.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Gmail MCP Server Constants
+ *
+ * These scopes are required for Gmail functionality and are hardcoded
+ * rather than externally configured since this server knows its own requirements.
+ */
+export declare const GOOGLE_SCOPE = "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email https://mail.google.com/";
+export declare const CHUNK_SIZE = 10;
+export declare const MAX_BATCH_SIZE = 500;
+export declare const DEFAULT_PAGE_SIZE = 50;
+export declare const MAX_PAGE_SIZE = 1000;

package/dist/cjs/constants.js

@@ -0,0 +1,39 @@
+/**
+ * Gmail MCP Server Constants
+ *
+ * These scopes are required for Gmail functionality and are hardcoded
+ * rather than externally configured since this server knows its own requirements.
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get CHUNK_SIZE () {
+        return CHUNK_SIZE;
+    },
+    get DEFAULT_PAGE_SIZE () {
+        return DEFAULT_PAGE_SIZE;
+    },
+    get GOOGLE_SCOPE () {
+        return GOOGLE_SCOPE;
+    },
+    get MAX_BATCH_SIZE () {
+        return MAX_BATCH_SIZE;
+    },
+    get MAX_PAGE_SIZE () {
+        return MAX_PAGE_SIZE;
+    }
+});
+var _email = require("@mcp-z/email");
+var GOOGLE_SCOPE = 'openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email https://mail.google.com/';
+var CHUNK_SIZE = _email.EMAIL_CHUNK_SIZE;
+var MAX_BATCH_SIZE = _email.EMAIL_MAX_BATCH_SIZE;
+var DEFAULT_PAGE_SIZE = 50; // Default number of items per page
+var MAX_PAGE_SIZE = 1000; // Maximum number of items per page
+/* CJS INTEROP */ if (exports.__esModule && exports.default) { try { Object.defineProperty(exports.default, '__esModule', { value: true }); for (var key in exports) { exports.default[key] = exports[key]; } } catch (_) {}; module.exports = exports.default; }

package/dist/cjs/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-gmail/src/constants.ts"],"sourcesContent":["/**\n * Gmail MCP Server Constants\n *\n * These scopes are required for Gmail functionality and are hardcoded\n * rather than externally configured since this server knows its own requirements.\n */\n\nimport { EMAIL_CHUNK_SIZE, EMAIL_MAX_BATCH_SIZE } from '@mcp-z/email';\n\n// Google OAuth scopes required for Gmail operations\nexport const GOOGLE_SCOPE = 'openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email https://mail.google.com/';\n\n// Batch processing configuration (from shared email constants)\nexport const CHUNK_SIZE = EMAIL_CHUNK_SIZE;\nexport const MAX_BATCH_SIZE = EMAIL_MAX_BATCH_SIZE;\n\n// Pagination configuration\nexport const DEFAULT_PAGE_SIZE = 50; // Default number of items per page\nexport const MAX_PAGE_SIZE = 1000; // Maximum number of items per page\n"],"names":["CHUNK_SIZE","DEFAULT_PAGE_SIZE","GOOGLE_SCOPE","MAX_BATCH_SIZE","MAX_PAGE_SIZE","EMAIL_CHUNK_SIZE","EMAIL_MAX_BATCH_SIZE"],"mappings":"AAAA;;;;;CAKC;;;;;;;;;;;QAQYA;eAAAA;;QAIAC;eAAAA;;QAPAC;eAAAA;;QAIAC;eAAAA;;QAIAC;eAAAA;;;qBAX0C;AAGhD,IAAMF,eAAe;AAGrB,IAAMF,aAAaK,uBAAgB;AACnC,IAAMF,iBAAiBG,2BAAoB;AAG3C,IAAML,oBAAoB,IAAI,mCAAmC;AACjE,IAAMG,gBAAgB,MAAM,mCAAmC"}

package/dist/cjs/email/composition/rfc822-builder.d.cts

@@ -0,0 +1,11 @@
+export interface Rfc822Args {
+    to?: string | string[];
+    cc?: string | string[];
+    bcc?: string | string[];
+    subject?: string;
+    body?: string;
+    from?: string;
+    /** Content type for the email body */
+    contentType?: 'text' | 'html';
+}
+export declare function buildRfc822FromArgs(args: Rfc822Args): string;

package/dist/cjs/email/composition/rfc822-builder.d.ts

@@ -0,0 +1,11 @@
+export interface Rfc822Args {
+    to?: string | string[];
+    cc?: string | string[];
+    bcc?: string | string[];
+    subject?: string;
+    body?: string;
+    from?: string;
+    /** Content type for the email body */
+    contentType?: 'text' | 'html';
+}
+export declare function buildRfc822FromArgs(args: Rfc822Args): string;

package/dist/cjs/email/composition/rfc822-builder.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "buildRfc822FromArgs", {
+    enumerable: true,
+    get: function() {
+        return buildRfc822FromArgs;
+    }
+});
+function buildRfc822FromArgs(args) {
+    var _args_to = args.to, to = _args_to === void 0 ? [] : _args_to, _args_cc = args.cc, cc = _args_cc === void 0 ? [] : _args_cc, _args_bcc = args.bcc, bcc = _args_bcc === void 0 ? [] : _args_bcc, _args_subject = args.subject, subject = _args_subject === void 0 ? '' : _args_subject, _args_body = args.body, body = _args_body === void 0 ? '' : _args_body, _args_from = args.from, from = _args_from === void 0 ? '' : _args_from, _args_contentType = args.contentType, contentType = _args_contentType === void 0 ? 'text' : _args_contentType;
+    var headers = [];
+    if (from) headers.push("From: ".concat(from));
+    if (to && to.length) headers.push("To: ".concat(Array.isArray(to) ? to.join(', ') : to));
+    if (cc && cc.length) headers.push("Cc: ".concat(Array.isArray(cc) ? cc.join(', ') : cc));
+    if (bcc && bcc.length) headers.push("Bcc: ".concat(Array.isArray(bcc) ? bcc.join(', ') : bcc));
+    if (subject) headers.push("Subject: ".concat(subject));
+    headers.push('MIME-Version: 1.0');
+    var mimeType = contentType === 'html' ? 'text/html' : 'text/plain';
+    headers.push("Content-Type: ".concat(mimeType, "; charset=utf-8"));
+    return "".concat(headers.join('\r\n'), "\r\n\r\n").concat(body);
+}
+/* CJS INTEROP */ if (exports.__esModule && exports.default) { try { Object.defineProperty(exports.default, '__esModule', { value: true }); for (var key in exports) { exports.default[key] = exports[key]; } } catch (_) {}; module.exports = exports.default; }

package/dist/cjs/email/composition/rfc822-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-gmail/src/email/composition/rfc822-builder.ts"],"sourcesContent":["export interface Rfc822Args {\n  to?: string | string[];\n  cc?: string | string[];\n  bcc?: string | string[];\n  subject?: string;\n  body?: string;\n  from?: string;\n  /** Content type for the email body */\n  contentType?: 'text' | 'html';\n}\n\nexport function buildRfc822FromArgs(args: Rfc822Args): string {\n  const { to = [], cc = [], bcc = [], subject = '', body = '', from = '', contentType = 'text' } = args;\n\n  const headers: string[] = [];\n\n  if (from) headers.push(`From: ${from}`);\n  if (to && to.length) headers.push(`To: ${Array.isArray(to) ? to.join(', ') : to}`);\n  if (cc && cc.length) headers.push(`Cc: ${Array.isArray(cc) ? cc.join(', ') : cc}`);\n  if (bcc && bcc.length) headers.push(`Bcc: ${Array.isArray(bcc) ? bcc.join(', ') : bcc}`);\n  if (subject) headers.push(`Subject: ${subject}`);\n\n  headers.push('MIME-Version: 1.0');\n  const mimeType = contentType === 'html' ? 'text/html' : 'text/plain';\n  headers.push(`Content-Type: ${mimeType}; charset=utf-8`);\n\n  return `${headers.join('\\r\\n')}\\r\\n\\r\\n${body}`;\n}\n"],"names":["buildRfc822FromArgs","args","to","cc","bcc","subject","body","from","contentType","headers","push","length","Array","isArray","join","mimeType"],"mappings":";;;;+BAWgBA;;;eAAAA;;;AAAT,SAASA,oBAAoBC,IAAgB;IAClD,eAAiGA,KAAzFC,IAAAA,2BAAK,EAAE,wBAAkFD,KAAhFE,IAAAA,2BAAK,EAAE,yBAAyEF,KAAvEG,KAAAA,6BAAM,EAAE,8BAA+DH,KAA7DI,SAAAA,qCAAU,iCAAmDJ,KAA/CK,MAAAA,+BAAO,8BAAwCL,KAApCM,MAAAA,+BAAO,qCAA6BN,KAAzBO,aAAAA,6CAAc;IAEtF,IAAMC,UAAoB,EAAE;IAE5B,IAAIF,MAAME,QAAQC,IAAI,CAAC,AAAC,SAAa,OAALH;IAChC,IAAIL,MAAMA,GAAGS,MAAM,EAAEF,QAAQC,IAAI,CAAC,AAAC,OAA6C,OAAvCE,MAAMC,OAAO,CAACX,MAAMA,GAAGY,IAAI,CAAC,QAAQZ;IAC7E,IAAIC,MAAMA,GAAGQ,MAAM,EAAEF,QAAQC,IAAI,CAAC,AAAC,OAA6C,OAAvCE,MAAMC,OAAO,CAACV,MAAMA,GAAGW,IAAI,CAAC,QAAQX;IAC7E,IAAIC,OAAOA,IAAIO,MAAM,EAAEF,QAAQC,IAAI,CAAC,AAAC,QAAiD,OAA1CE,MAAMC,OAAO,CAACT,OAAOA,IAAIU,IAAI,CAAC,QAAQV;IAClF,IAAIC,SAASI,QAAQC,IAAI,CAAC,AAAC,YAAmB,OAARL;IAEtCI,QAAQC,IAAI,CAAC;IACb,IAAMK,WAAWP,gBAAgB,SAAS,cAAc;IACxDC,QAAQC,IAAI,CAAC,AAAC,iBAAyB,OAATK,UAAS;IAEvC,OAAO,AAAC,GAAiCT,OAA/BG,QAAQK,IAAI,CAAC,SAAQ,YAAe,OAALR;AAC3C"}

package/dist/cjs/email/messages/fetch-message.d.cts

@@ -0,0 +1,24 @@
+import type { gmail_v1 } from 'googleapis';
+export type FetchMode = 'metadata' | 'full';
+export interface NormalizedAddress {
+    address?: string | undefined;
+    name?: string | undefined;
+}
+export interface NormalizedMessage {
+    id: string;
+    threadId?: string | undefined;
+    date?: string | undefined;
+    subject?: string | undefined;
+    from?: NormalizedAddress | undefined;
+    to?: string[] | undefined;
+    cc?: string[] | undefined;
+    bcc?: string[] | undefined;
+    snippet?: string | undefined;
+    labels?: string[] | undefined;
+    body?: string | undefined;
+}
+export interface GmailDeps {
+    /** googleapis Gmail client created via createGmailClient(provider). */
+    gmail: gmail_v1.Gmail;
+}
+export declare function fetchMessage(deps: GmailDeps, id: string, mode: FetchMode): Promise<NormalizedMessage>;

package/dist/cjs/email/messages/fetch-message.d.ts

@@ -0,0 +1,24 @@
+import type { gmail_v1 } from 'googleapis';
+export type FetchMode = 'metadata' | 'full';
+export interface NormalizedAddress {
+    address?: string | undefined;
+    name?: string | undefined;
+}
+export interface NormalizedMessage {
+    id: string;
+    threadId?: string | undefined;
+    date?: string | undefined;
+    subject?: string | undefined;
+    from?: NormalizedAddress | undefined;
+    to?: string[] | undefined;
+    cc?: string[] | undefined;
+    bcc?: string[] | undefined;
+    snippet?: string | undefined;
+    labels?: string[] | undefined;
+    body?: string | undefined;
+}
+export interface GmailDeps {
+    /** googleapis Gmail client created via createGmailClient(provider). */
+    gmail: gmail_v1.Gmail;
+}
+export declare function fetchMessage(deps: GmailDeps, id: string, mode: FetchMode): Promise<NormalizedMessage>;