@mcp-z/mcp-sheets 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,181 @@
+# @mcp-z/mcp-sheets
+
+Docs: https://mcp-z.github.io/mcp-sheets
+Google Sheets MCP server for reading, writing, and formatting spreadsheets.
+
+## Common uses
+
+- Find spreadsheets and sheets
+- Append and update data
+- Apply formatting, validation, and charts
+
+## Transports
+
+MCP supports stdio and HTTP.
+
+**Stdio**
+```json
+{
+  "mcpServers": {
+    "sheets": {
+      "command": "npx",
+      "args": ["-y", "@mcp-z/mcp-sheets"]
+    }
+  }
+}
+```
+
+**HTTP**
+```json
+{
+  "mcpServers": {
+    "sheets": {
+      "type": "http",
+      "url": "http://localhost:9004/mcp",
+      "start": {
+        "command": "npx",
+        "args": ["-y", "@mcp-z/mcp-sheets", "--port=9004"]
+      }
+    }
+  }
+}
+```
+
+`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 Google Sheets 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": {
+    "sheets": {
+      "command": "npx",
+      "args": ["-y", "@mcp-z/mcp-sheets"],
+      "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": {
+    "sheets": {
+      "command": "npx",
+      "args": ["-y", "@mcp-z/mcp-sheets", "--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": {
+    "sheets-dcr": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@mcp-z/mcp-sheets",
+        "--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 sheets --tools
+
+# Find a spreadsheet
+mcp-z call sheets spreadsheet-find '{"spreadsheetRef":"Quarterly Report"}'
+```
+
+## Tools
+
+1. cells-format
+2. chart-create
+3. columns-get
+4. columns-update
+5. csv-get-columns
+6. dimensions-batch-update
+7. dimensions-move
+8. rows-append
+9. rows-csv-append
+10. rows-get
+11. sheet-copy
+12. sheet-copy-to
+13. sheet-create
+14. sheet-delete
+15. sheet-find
+16. sheet-rename
+17. spreadsheet-copy
+18. spreadsheet-create
+19. spreadsheet-find
+20. spreadsheet-rename
+21. validation-set
+22. values-batch-update
+23. values-clear
+24. values-csv-update
+25. values-replace
+26. values-search
+
+## Resources
+
+1. spreadsheet
+
+## Prompts
+
+1. a1-notation
+
+## 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-sheets')).catch((err) => { console.log(err); process.exit(-1); });");
+else require('../dist/cjs/index.js')(process.argv.slice(2), 'mcp-sheets');

package/dist/cjs/constants.d.cts

@@ -0,0 +1,7 @@
+/**
+ * Sheets MCP Server Constants
+ *
+ * These scopes are required for Google Sheets and Drive 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://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive";

package/dist/cjs/constants.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Sheets MCP Server Constants
+ *
+ * These scopes are required for Google Sheets and Drive 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://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive";

package/dist/cjs/constants.js

@@ -0,0 +1,18 @@
+/**
+ * Sheets MCP Server Constants
+ *
+ * These scopes are required for Google Sheets and Drive functionality and are hardcoded
+ * rather than externally configured since this server knows its own requirements.
+ */ // Google OAuth scopes required for Sheets and Drive operations
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "GOOGLE_SCOPE", {
+    enumerable: true,
+    get: function() {
+        return GOOGLE_SCOPE;
+    }
+});
+var GOOGLE_SCOPE = 'openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive';
+/* 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-sheets/src/constants.ts"],"sourcesContent":["/**\n * Sheets MCP Server Constants\n *\n * These scopes are required for Google Sheets and Drive functionality and are hardcoded\n * rather than externally configured since this server knows its own requirements.\n */\n\n// Google OAuth scopes required for Sheets and Drive operations\nexport const GOOGLE_SCOPE = 'openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive';\n"],"names":["GOOGLE_SCOPE"],"mappings":"AAAA;;;;;CAKC,GAED,+DAA+D;;;;;+BAClDA;;;eAAAA;;;AAAN,IAAMA,eAAe"}

package/dist/cjs/index.d.cts

@@ -0,0 +1,8 @@
+import type { ServerConfig } from './types.js';
+export { GOOGLE_SCOPE } from './constants.js';
+export * as mcp from './mcp/index.js';
+export * as schemas from './schemas/index.js';
+export * as setup from './setup/index.js';
+export * from './types.js';
+export declare function startServer(config: ServerConfig): Promise<void>;
+export default function main(): Promise<void>;

package/dist/cjs/index.d.ts

@@ -0,0 +1,8 @@
+import type { ServerConfig } from './types.js';
+export { GOOGLE_SCOPE } from './constants.js';
+export * as mcp from './mcp/index.js';
+export * as schemas from './schemas/index.js';
+export * as setup from './setup/index.js';
+export * from './types.js';
+export declare function startServer(config: ServerConfig): Promise<void>;
+export default function main(): Promise<void>;

package/dist/cjs/index.js

@@ -0,0 +1,314 @@
+"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 GOOGLE_SCOPE () {
+        return _constantsts.GOOGLE_SCOPE;
+    },
+    get default () {
+        return main;
+    },
+    get mcp () {
+        return _index;
+    },
+    get schemas () {
+        return _index1;
+    },
+    get setup () {
+        return _index2;
+    },
+    get startServer () {
+        return startServer;
+    }
+});
+var _config = require("./setup/config.js");
+var _http = require("./setup/http.js");
+var _stdio = require("./setup/stdio.js");
+var _constantsts = require("./constants.js");
+var _index = /*#__PURE__*/ _interop_require_wildcard(require("./mcp/index.js"));
+var _index1 = /*#__PURE__*/ _interop_require_wildcard(require("./schemas/index.js"));
+var _index2 = /*#__PURE__*/ _interop_require_wildcard(require("./setup/index.js"));
+_export_star(require("./types.js"), exports);
+function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}
+function _getRequireWildcardCache(nodeInterop) {
+    if (typeof WeakMap !== "function") return null;
+    var cacheBabelInterop = new WeakMap();
+    var cacheNodeInterop = new WeakMap();
+    return (_getRequireWildcardCache = function(nodeInterop) {
+        return nodeInterop ? cacheNodeInterop : cacheBabelInterop;
+    })(nodeInterop);
+}
+function _interop_require_wildcard(obj, nodeInterop) {
+    if (!nodeInterop && obj && obj.__esModule) {
+        return obj;
+    }
+    if (obj === null || typeof obj !== "object" && typeof obj !== "function") {
+        return {
+            default: obj
+        };
+    }
+    var cache = _getRequireWildcardCache(nodeInterop);
+    if (cache && cache.has(obj)) {
+        return cache.get(obj);
+    }
+    var newObj = {
+        __proto__: null
+    };
+    var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor;
+    for(var key in obj){
+        if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) {
+            var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null;
+            if (desc && (desc.get || desc.set)) {
+                Object.defineProperty(newObj, key, desc);
+            } else {
+                newObj[key] = obj[key];
+            }
+        }
+    }
+    newObj.default = obj;
+    if (cache) {
+        cache.set(obj, newObj);
+    }
+    return newObj;
+}
+function _ts_generator(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
+        }
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
+function startServer(config) {
+    return _async_to_generator(function() {
+        var _ref, logger, close, _tmp;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    if (!(config.transport.type === 'stdio')) return [
+                        3,
+                        2
+                    ];
+                    return [
+                        4,
+                        (0, _stdio.createStdioServer)(config)
+                    ];
+                case 1:
+                    _tmp = _state.sent();
+                    return [
+                        3,
+                        4
+                    ];
+                case 2:
+                    return [
+                        4,
+                        (0, _http.createHTTPServer)(config)
+                    ];
+                case 3:
+                    _tmp = _state.sent();
+                    _state.label = 4;
+                case 4:
+                    _ref = _tmp, logger = _ref.logger, close = _ref.close;
+                    process.on('SIGINT', function() {
+                        return _async_to_generator(function() {
+                            return _ts_generator(this, function(_state) {
+                                switch(_state.label){
+                                    case 0:
+                                        return [
+                                            4,
+                                            close()
+                                        ];
+                                    case 1:
+                                        _state.sent();
+                                        process.exit(0);
+                                        return [
+                                            2
+                                        ];
+                                }
+                            });
+                        })();
+                    });
+                    logger.info("Server started with ".concat(config.transport.type, " transport"));
+                    return [
+                        4,
+                        new Promise(function() {})
+                    ];
+                case 5:
+                    _state.sent();
+                    return [
+                        2
+                    ];
+            }
+        });
+    })();
+}
+function main() {
+    return _async_to_generator(function() {
+        var versionHelpResult, config;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    // Check for help/version flags FIRST, before config parsing
+                    versionHelpResult = (0, _config.handleVersionHelp)(process.argv);
+                    if (versionHelpResult.handled) {
+                        console.log(versionHelpResult.output);
+                        process.exit(0);
+                    }
+                    // Only parse config if no help/version flags
+                    config = (0, _config.createConfig)();
+                    return [
+                        4,
+                        startServer(config)
+                    ];
+                case 1:
+                    _state.sent();
+                    return [
+                        2
+                    ];
+            }
+        });
+    })();
+}
+if (process.argv[1] === new URL(require("url").pathToFileURL(__filename).toString()).pathname) {
+    main();
+}
+/* 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/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-sheets/src/index.ts"],"sourcesContent":["import { createConfig, handleVersionHelp } from './setup/config.js';\nimport { createHTTPServer } from './setup/http.js';\nimport { createStdioServer } from './setup/stdio.js';\nimport type { ServerConfig } from './types.js';\n\nexport { GOOGLE_SCOPE } from './constants.ts';\nexport * as mcp from './mcp/index.js';\nexport * as schemas from './schemas/index.js';\nexport * as setup from './setup/index.js';\nexport * from './types.js';\n\nexport async function startServer(config: ServerConfig): Promise<void> {\n  const { logger, close } = config.transport.type === 'stdio' ? await createStdioServer(config) : await createHTTPServer(config);\n\n  process.on('SIGINT', async () => {\n    await close();\n    process.exit(0);\n  });\n\n  logger.info(`Server started with ${config.transport.type} transport`);\n  await new Promise(() => {});\n}\n\nexport default async function main(): Promise<void> {\n  // Check for help/version flags FIRST, before config parsing\n  const versionHelpResult = handleVersionHelp(process.argv);\n  if (versionHelpResult.handled) {\n    console.log(versionHelpResult.output);\n    process.exit(0);\n  }\n\n  // Only parse config if no help/version flags\n  const config = createConfig();\n  await startServer(config);\n}\n\nif (process.argv[1] === new URL(import.meta.url).pathname) {\n  main();\n}\n"],"names":["GOOGLE_SCOPE","main","mcp","schemas","setup","startServer","config","logger","close","transport","type","createStdioServer","createHTTPServer","process","on","exit","info","Promise","versionHelpResult","handleVersionHelp","argv","handled","console","log","output","createConfig","URL","pathname"],"mappings":";;;;;;;;;;;QAKSA;eAAAA,yBAAY;;QAkBrB;eAA8BC;;QAjBlBC;;;QACAC;;;QACAC;;;QAGUC;eAAAA;;;sBAX0B;oBACf;qBACC;2BAGL;6DACR;8DACI;8DACF;qBACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEP,SAAeA,YAAYC,MAAoB;;YAC1BA,MAAlBC,QAAQC;;;;yBAAUF,CAAAA,OAAOG,SAAS,CAACC,IAAI,KAAK,OAAM,GAAhCJ;;;;oBAAoC;;wBAAMK,IAAAA,wBAAiB,EAACL;;;2BAAxB;;;;;;oBAAkC;;wBAAMM,IAAAA,sBAAgB,EAACN;;;2BAAvB;;;oBAAtEA,aAAlBC,SAAkBD,KAAlBC,QAAQC,QAAUF,KAAVE;oBAEhBK,QAAQC,EAAE,CAAC,UAAU;;;;;wCACnB;;4CAAMN;;;wCAAN;wCACAK,QAAQE,IAAI,CAAC;;;;;;wBACf;;oBAEAR,OAAOS,IAAI,CAAC,AAAC,uBAA4C,OAAtBV,OAAOG,SAAS,CAACC,IAAI,EAAC;oBACzD;;wBAAM,IAAIO,QAAQ,YAAO;;;oBAAzB;;;;;;IACF;;AAEe,SAAehB;;YAEtBiB,mBAOAZ;;;;oBARN,4DAA4D;oBACtDY,oBAAoBC,IAAAA,yBAAiB,EAACN,QAAQO,IAAI;oBACxD,IAAIF,kBAAkBG,OAAO,EAAE;wBAC7BC,QAAQC,GAAG,CAACL,kBAAkBM,MAAM;wBACpCX,QAAQE,IAAI,CAAC;oBACf;oBAEA,6CAA6C;oBACvCT,SAASmB,IAAAA,oBAAY;oBAC3B;;wBAAMpB,YAAYC;;;oBAAlB;;;;;;IACF;;AAEA,IAAIO,QAAQO,IAAI,CAAC,EAAE,KAAK,IAAIM,IAAI,qDAAiBC,QAAQ,EAAE;IACzD1B;AACF"}

package/dist/cjs/lib/create-store.d.cts

@@ -0,0 +1,2 @@
+import type Keyv from 'keyv';
+export default function createStore<T>(uri: string): Promise<Keyv<T>>;

package/dist/cjs/lib/create-store.d.ts

@@ -0,0 +1,2 @@
+import type Keyv from 'keyv';
+export default function createStore<T>(uri: string): Promise<Keyv<T>>;