@alanse/mcp-server-google-workspace 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alanse inc.
+
+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,173 @@
+# MCP Server - Google Workspace
+
+**The most comprehensive MCP server for Google Workspace** - Complete programmatic control over Sheets, Drive, and future Docs, Calendar, Forms integration.
+
+🚀 **Current Status**: 59 tools (Drive: 2, Sheets: 57)
+📅 **Roadmap**: Google Docs, Calendar, Forms, Gmail, Slides
+
+This is an extended version of [@isaacphi/mcp-gdrive](https://github.com/isaacphi/mcp-gdrive), adding **53 additional Google Sheets API tools** for complete spreadsheet management and preparing for comprehensive Google Workspace coverage.
+
+## Credits
+
+This project is based on:
+- Original code by **Anthropic, PBC** from [MCP Servers](https://github.com/modelcontextprotocol/servers/tree/main/src/gdrive) (MIT License)
+- Enhanced by **Phil Isaac** in [@isaacphi/mcp-gdrive](https://github.com/isaacphi/mcp-gdrive) (MIT License)
+- **Extended implementation** by **Alanse株式会社 / Daichi Okazaki** (2026)
+
+All contributions are licensed under the MIT License.
+
+## 🚀 Features
+
+### 📊 Extended Google Sheets API Implementation
+
+**59 Total Tools** = 2 GDrive + **57 Google Sheets** operations
+
+#### Tool Categories
+
+**Google Drive Operations (2 tools)**
+- Search & File Management
+
+**Sheet Management (13 tools)**
+- Create, Read, List, Add, Delete, Rename Sheets
+- Insert/Delete Rows & Columns
+- Copy, Duplicate, Copy Between Spreadsheets
+
+**Data Operations (9 tools)**
+- Cell Update, Batch Update, Append Data
+- Clear Data, Batch Clear
+- Sort, Find & Replace
+- Data Validation, Filter Creation
+
+**Formatting (8 tools)**
+- Cell Formatting (Font, Color, Alignment)
+- Merge/Unmerge Cells
+- Borders, Auto-resize
+- Number Formats, Freeze Rows/Columns
+
+**Charts (10 tools)**
+- Basic Charts (Column, Bar, Line, Area, Pie, Scatter)
+- Advanced Charts (Histogram, Waterfall, Candlestick, Combo, Bubble, Treemap, Org Chart)
+- Chart Update & Delete
+
+**Protection & Named Ranges (7 tools)**
+- Protected Ranges (Add/Update/Delete)
+- Named Ranges (Add/Update/Delete)
+- Conditional Formatting
+
+**Advanced Features (8 tools)**
+- Filter Views & Pivot Tables
+- Dimension Groups (Row/Column Grouping)
+- Developer Metadata (Custom Metadata Storage)
+
+For complete tool documentation, see [docs/api-comparison.md](./docs/api-comparison.md)
+
+### Resources
+
+The server provides access to Google Drive files:
+
+- **Files** (`gdrive:///<file_id>`)
+  - Supports all file types
+  - Google Workspace files are automatically exported:
+    - Docs → Markdown
+    - Sheets → CSV
+    - Presentations → Plain text
+    - Drawings → PNG
+  - Other files are provided in their native format
+
+## Getting started
+
+1. [Create a new Google Cloud project](https://console.cloud.google.com/projectcreate)
+2. [Enable the Google Drive API](https://console.cloud.google.com/workspace-api/products)
+3. [Configure an OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent) ("internal" is fine for testing)
+4. Add OAuth scopes `https://www.googleapis.com/auth/drive.readonly`, `https://www.googleapis.com/auth/spreadsheets`
+5. In order to allow interaction with sheets and docs you will also need to enable the [Google Sheets API](https://console.cloud.google.com/apis/api/sheets.googleapis.com/) and [Google Docs API](https://console.cloud.google.com/marketplace/product/google/docs.googleapis.com) in your workspaces Enabled API and Services section.
+6. [Create an OAuth Client ID](https://console.cloud.google.com/apis/credentials/oauthclient) for application type "Desktop App"
+7. Download the JSON file of your client's OAuth keys
+8. Rename the key file to `gcp-oauth.keys.json` and place into the path you specify with `GDRIVE_CREDS_DIR` (i.e. `/Users/username/.config/mcp-gdrive`)
+9. Note your OAuth Client ID and Client Secret. They must be provided as environment variables along with your configuration directory.
+10. You will also need to setup a .env file within the project with the following fields. You can find the Client ID and Client Secret in the Credentials section of the Google Cloud Console.
+
+```
+GDRIVE_CREDS_DIR=/path/to/config/directory
+CLIENT_ID=<CLIENT_ID>
+CLIENT_SECRET=<CLIENT_SECRET>
+```
+
+Make sure to build the server with either `npm run build` or `npm run watch`.
+
+### Authentication
+
+Next you will need to run `node ./dist/index.js` to trigger the authentication step
+
+You will be prompted to authenticate with your browser. You must authenticate with an account in the same organization as your Google Cloud project.
+
+Your OAuth token is saved in the directory specified by the `GDRIVE_CREDS_DIR` environment variable.
+
+![Authentication Prompt](https://i.imgur.com/TbyV6Yq.png)
+
+### Usage with Desktop App
+
+To integrate this server with the desktop app, add the following to your app's server configuration:
+
+```json
+{
+  "mcpServers": {
+    "google-workspace": {
+      "command": "npx",
+      "args": ["-y", "@alanse/mcp-server-google-workspace"],
+      "env": {
+        "CLIENT_ID": "<CLIENT_ID>",
+        "CLIENT_SECRET": "<CLIENT_SECRET>",
+        "GDRIVE_CREDS_DIR": "/path/to/config/directory"
+      }
+    }
+  }
+}
+```
+
+## 📈 Project Status
+
+✅ **Phase 1-12 Complete** (2026-01-06)
+- **59 Tools Implemented** (57 Sheets + 2 GDrive)
+- **155 Tests** (100% Pass Rate)
+- **Production Ready**
+
+## 🗺️ Roadmap
+
+### Current: Google Sheets & Drive ✅
+
+- ✅ **Google Drive**: 2 tools (Search, Read)
+- ✅ **Google Sheets**: 57 tools (Complete API coverage)
+
+### Coming Soon
+
+- 📝 **Google Docs**: Document creation, editing, formatting (~15-20 tools)
+- 📅 **Google Calendar**: Event management, scheduling (~10-15 tools)
+- 📋 **Google Forms**: Form creation, response management (~10-15 tools)
+- 📧 **Gmail**: Email operations, thread management (~10-15 tools)
+- 🎬 **Google Slides**: Presentation creation, editing (~15-20 tools)
+
+**Goal**: 100+ tools covering the entire Google Workspace ecosystem
+
+## 📄 License
+
+This project is licensed under the **MIT License**.
+
+### Copyright Notices
+
+- Original code: © 2024 Anthropic, PBC
+- Base implementation: © 2024 Phil Isaac
+- Extended implementation: © 2026 Alanse株式会社 / Daichi Okazaki
+
+You are free to use, modify, and distribute this software under the terms of the MIT License. See the [LICENSE](./LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+Special thanks to:
+- **Anthropic, PBC** for the original MCP server implementation
+- **Phil Isaac** for the enhanced Google Drive & Sheets integration
+- The **Model Context Protocol** team for the excellent framework
+
+## 📚 Related Documentation
+
+- [docs/api-comparison.md](./docs/api-comparison.md) - MCP vs Google Sheets API comparison

package/dist/auth.js

@@ -0,0 +1,135 @@
+import { authenticate } from "@google-cloud/local-auth";
+import { google } from "googleapis";
+import fs from "fs";
+import path from "path";
+export const SCOPES = [
+    "https://www.googleapis.com/auth/drive.readonly",
+    "https://www.googleapis.com/auth/spreadsheets",
+];
+// Get credentials directory from environment variable or use default
+const CREDS_DIR = process.env.GDRIVE_CREDS_DIR ||
+    path.join(path.dirname(new URL(import.meta.url).pathname), "../../../");
+// Ensure the credentials directory exists
+function ensureCredsDirectory() {
+    try {
+        fs.mkdirSync(CREDS_DIR, { recursive: true });
+        console.error(`Ensured credentials directory exists at: ${CREDS_DIR}`);
+    }
+    catch (error) {
+        console.error(`Failed to create credentials directory: ${CREDS_DIR}`, error);
+        throw error;
+    }
+}
+const credentialsPath = path.join(CREDS_DIR, ".gdrive-server-credentials.json");
+async function authenticateWithTimeout(keyfilePath, SCOPES, timeoutMs = 30000) {
+    const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error("Authentication timed out")), timeoutMs));
+    const authPromise = authenticate({
+        keyfilePath,
+        scopes: SCOPES,
+    });
+    try {
+        return await Promise.race([authPromise, timeoutPromise]);
+    }
+    catch (error) {
+        console.error(error);
+        return null;
+    }
+}
+async function authenticateAndSaveCredentials() {
+    console.error("Launching auth flow…");
+    console.error("Using credentials path:", credentialsPath);
+    const keyfilePath = path.join(CREDS_DIR, "gcp-oauth.keys.json");
+    console.error("Using keyfile path:", keyfilePath);
+    const auth = await authenticateWithTimeout(keyfilePath, SCOPES);
+    if (auth) {
+        const newAuth = new google.auth.OAuth2();
+        newAuth.setCredentials(auth.credentials);
+    }
+    try {
+        const { credentials } = await auth.refreshAccessToken();
+        console.error("Received new credentials with scopes:", credentials.scope);
+        // Ensure directory exists before saving
+        ensureCredsDirectory();
+        fs.writeFileSync(credentialsPath, JSON.stringify(credentials, null, 2));
+        console.error("Credentials saved successfully with refresh token to:", credentialsPath);
+        auth.setCredentials(credentials);
+        return auth;
+    }
+    catch (error) {
+        console.error("Error refreshing token during initial auth:", error);
+        return auth;
+    }
+}
+// Try to load credentials without prompting for auth
+export async function loadCredentialsQuietly() {
+    console.error("Attempting to load credentials from:", credentialsPath);
+    const oauth2Client = new google.auth.OAuth2(process.env.CLIENT_ID, process.env.CLIENT_SECRET);
+    if (!fs.existsSync(credentialsPath)) {
+        console.error("No credentials file found");
+        return null;
+    }
+    try {
+        const savedCreds = JSON.parse(fs.readFileSync(credentialsPath, "utf-8"));
+        console.error("Loaded existing credentials with scopes:", savedCreds.scope);
+        oauth2Client.setCredentials(savedCreds);
+        const expiryDate = new Date(savedCreds.expiry_date);
+        const now = new Date();
+        const fiveMinutes = 5 * 60 * 1000;
+        const timeToExpiry = expiryDate.getTime() - now.getTime();
+        console.error("Token expiry status:", {
+            expiryDate: expiryDate.toISOString(),
+            timeToExpiryMinutes: Math.floor(timeToExpiry / (60 * 1000)),
+            hasRefreshToken: !!savedCreds.refresh_token,
+        });
+        if (timeToExpiry < fiveMinutes && savedCreds.refresh_token) {
+            console.error("Attempting to refresh token using refresh_token");
+            try {
+                const response = await oauth2Client.refreshAccessToken();
+                const newCreds = response.credentials;
+                ensureCredsDirectory();
+                fs.writeFileSync(credentialsPath, JSON.stringify(newCreds, null, 2));
+                oauth2Client.setCredentials(newCreds);
+                console.error("Token refreshed and saved successfully");
+            }
+            catch (error) {
+                console.error("Failed to refresh token:", error);
+                return null;
+            }
+        }
+        return oauth2Client;
+    }
+    catch (error) {
+        console.error("Error loading credentials:", error);
+        return null;
+    }
+}
+// Get valid credentials, prompting for auth if necessary
+export async function getValidCredentials(forceAuth = false) {
+    if (!forceAuth) {
+        const quietAuth = await loadCredentialsQuietly();
+        if (quietAuth) {
+            return quietAuth;
+        }
+    }
+    return await authenticateAndSaveCredentials();
+}
+// Background refresh that never prompts for auth
+export function setupTokenRefresh() {
+    console.error("Setting up automatic token refresh interval (45 minutes)");
+    return setInterval(async () => {
+        try {
+            console.error("Running scheduled token refresh check");
+            const auth = await loadCredentialsQuietly();
+            if (auth) {
+                google.options({ auth });
+                console.error("Completed scheduled token refresh");
+            }
+            else {
+                console.error("Skipping token refresh - no valid credentials");
+            }
+        }
+        catch (error) {
+            console.error("Error in automatic token refresh:", error);
+        }
+    }, 45 * 60 * 1000);
+}

package/dist/index.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { google } from "googleapis";
+import { getValidCredentials, setupTokenRefresh, loadCredentialsQuietly, } from "./auth.js";
+import { tools } from "./tools/index.js";
+const drive = google.drive("v3");
+const server = new Server({
+    name: "example-servers/gdrive",
+    version: "0.1.0",
+}, {
+    capabilities: {
+        resources: {
+            schemes: ["gdrive"], // Declare that we handle gdrive:/// URIs
+            listable: true, // Support listing available resources
+            readable: true, // Support reading resource contents
+        },
+        tools: {},
+    },
+});
+// Ensure we have valid credentials before making API calls
+async function ensureAuth() {
+    const auth = await getValidCredentials();
+    google.options({ auth });
+    return auth;
+}
+async function ensureAuthQuietly() {
+    const auth = await loadCredentialsQuietly();
+    if (auth) {
+        google.options({ auth });
+    }
+    return auth;
+}
+server.setRequestHandler(ListResourcesRequestSchema, async (request) => {
+    await ensureAuthQuietly();
+    const pageSize = 10;
+    const params = {
+        pageSize,
+        fields: "nextPageToken, files(id, name, mimeType)",
+    };
+    if (request.params?.cursor) {
+        params.pageToken = request.params.cursor;
+    }
+    const res = await drive.files.list(params);
+    const files = res.data.files;
+    return {
+        resources: files.map((file) => ({
+            uri: `gdrive:///${file.id}`,
+            mimeType: file.mimeType,
+            name: file.name,
+        })),
+        nextCursor: res.data.nextPageToken,
+    };
+});
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    await ensureAuthQuietly();
+    const fileId = request.params.uri.replace("gdrive:///", "");
+    const readFileTool = tools[1]; // gdrive_read_file is the second tool
+    const result = await readFileTool.handler({ fileId });
+    // Extract the file contents from the tool response
+    const fileContents = result.content[0].text.split("\n\n")[1]; // Skip the "Contents of file:" prefix
+    return {
+        contents: [
+            {
+                uri: request.params.uri,
+                mimeType: "text/plain", // You might want to determine this dynamically
+                text: fileContents,
+            },
+        ],
+    };
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: tools.map(({ name, description, inputSchema }) => ({
+            name,
+            description,
+            inputSchema,
+        })),
+    };
+});
+// Helper function to convert internal tool response to SDK format
+function convertToolResponse(response) {
+    return {
+        _meta: {},
+        content: response.content,
+        isError: response.isError,
+    };
+}
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    await ensureAuth();
+    const tool = tools.find((t) => t.name === request.params.name);
+    if (!tool) {
+        throw new Error("Tool not found");
+    }
+    const result = await tool.handler(request.params.arguments);
+    return convertToolResponse(result);
+});
+async function startServer() {
+    try {
+        console.error("Starting server");
+        // Add this line to force authentication at startup
+        await ensureAuth(); // This will trigger the auth flow if no valid credentials exist
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        // Set up periodic token refresh that never prompts for auth
+        setupTokenRefresh();
+    }
+    catch (error) {
+        console.error("Error starting server:", error);
+        process.exit(1);
+    }
+}
+// Start server immediately
+startServer().catch(console.error);

package/dist/tools/basic/gsheets_add_sheet.js

@@ -0,0 +1,65 @@
+import { google } from "googleapis";
+export const schema = {
+    name: "gsheets_add_sheet",
+    description: "Add a new sheet (tab) to a Google Spreadsheet",
+    inputSchema: {
+        type: "object",
+        properties: {
+            spreadsheetId: {
+                type: "string",
+                description: "The ID of the spreadsheet",
+            },
+            title: {
+                type: "string",
+                description: "The name of the new sheet",
+            },
+            index: {
+                type: "number",
+                description: "Optional position index (0-based) where the sheet should be inserted",
+            },
+        },
+        required: ["spreadsheetId", "title"],
+    },
+};
+export async function addSheet(args) {
+    try {
+        const sheets = google.sheets("v4");
+        const request = {
+            addSheet: {
+                properties: {
+                    title: args.title,
+                },
+            },
+        };
+        if (args.index !== undefined) {
+            request.addSheet.properties.index = args.index;
+        }
+        const response = await sheets.spreadsheets.batchUpdate({
+            spreadsheetId: args.spreadsheetId,
+            requestBody: {
+                requests: [request],
+            },
+        });
+        const addedSheet = response.data.replies?.[0]?.addSheet?.properties;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Successfully added sheet "${addedSheet?.title}" (ID: ${addedSheet?.sheetId}, Index: ${addedSheet?.index})`,
+                },
+            ],
+            isError: false,
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error adding sheet: ${error.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/tools/basic/gsheets_copy_sheet.js

@@ -0,0 +1,56 @@
+import { google } from "googleapis";
+export const schema = {
+    name: "gsheets_copy_sheet",
+    description: "Copy a sheet to another spreadsheet or within the same spreadsheet",
+    inputSchema: {
+        type: "object",
+        properties: {
+            sourceSpreadsheetId: {
+                type: "string",
+                description: "The ID of the source spreadsheet",
+            },
+            sourceSheetId: {
+                type: "number",
+                description: "The ID of the sheet to copy",
+            },
+            destinationSpreadsheetId: {
+                type: "string",
+                description: "The ID of the destination spreadsheet",
+            },
+        },
+        required: ["sourceSpreadsheetId", "sourceSheetId", "destinationSpreadsheetId"],
+    },
+};
+export async function copySheet(args) {
+    const sheets = google.sheets("v4");
+    try {
+        const response = await sheets.spreadsheets.sheets.copyTo({
+            spreadsheetId: args.sourceSpreadsheetId,
+            sheetId: args.sourceSheetId,
+            requestBody: {
+                destinationSpreadsheetId: args.destinationSpreadsheetId,
+            },
+        });
+        const copiedSheet = response.data;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Successfully copied sheet to destination. New sheet ID: ${copiedSheet.sheetId}, Title: "${copiedSheet.title}"`,
+                },
+            ],
+            isError: false,
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error copying sheet: ${error.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/tools/basic/gsheets_copy_to.js

@@ -0,0 +1,113 @@
+import { google } from "googleapis";
+export const schema = {
+    name: "gsheets_copy_to",
+    description: "Copy data from one range to another range using cut/paste",
+    inputSchema: {
+        type: "object",
+        properties: {
+            spreadsheetId: {
+                type: "string",
+                description: "The ID of the spreadsheet",
+            },
+            sourceSheetId: {
+                type: "number",
+                description: "The ID of the source sheet",
+            },
+            sourceStartRow: {
+                type: "number",
+                description: "Source starting row index (0-based)",
+            },
+            sourceStartColumn: {
+                type: "number",
+                description: "Source starting column index (0-based)",
+            },
+            sourceEndRow: {
+                type: "number",
+                description: "Source ending row index (exclusive, 0-based)",
+            },
+            sourceEndColumn: {
+                type: "number",
+                description: "Source ending column index (exclusive, 0-based)",
+            },
+            destinationSheetId: {
+                type: "number",
+                description: "The ID of the destination sheet",
+            },
+            destinationStartRow: {
+                type: "number",
+                description: "Destination starting row index (0-based)",
+            },
+            destinationStartColumn: {
+                type: "number",
+                description: "Destination starting column index (0-based)",
+            },
+            pasteType: {
+                type: "string",
+                enum: ["NORMAL", "VALUES", "FORMAT", "FORMULA"],
+                description: "What to paste (default: NORMAL - all data)",
+            },
+        },
+        required: [
+            "spreadsheetId",
+            "sourceSheetId",
+            "sourceStartRow",
+            "sourceStartColumn",
+            "sourceEndRow",
+            "sourceEndColumn",
+            "destinationSheetId",
+            "destinationStartRow",
+            "destinationStartColumn",
+        ],
+    },
+};
+export async function copyTo(args) {
+    const sheets = google.sheets("v4");
+    try {
+        await sheets.spreadsheets.batchUpdate({
+            spreadsheetId: args.spreadsheetId,
+            requestBody: {
+                requests: [
+                    {
+                        copyPaste: {
+                            source: {
+                                sheetId: args.sourceSheetId,
+                                startRowIndex: args.sourceStartRow,
+                                endRowIndex: args.sourceEndRow,
+                                startColumnIndex: args.sourceStartColumn,
+                                endColumnIndex: args.sourceEndColumn,
+                            },
+                            destination: {
+                                sheetId: args.destinationSheetId,
+                                startRowIndex: args.destinationStartRow,
+                                startColumnIndex: args.destinationStartColumn,
+                            },
+                            pasteType: args.pasteType || "NORMAL",
+                        },
+                    },
+                ],
+            },
+        });
+        const sourceRange = `R${args.sourceStartRow}C${args.sourceStartColumn}:R${args.sourceEndRow - 1}C${args.sourceEndColumn - 1}`;
+        const destRange = `R${args.destinationStartRow}C${args.destinationStartColumn}`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Successfully copied data from sheet ${args.sourceSheetId} (${sourceRange}) to sheet ${args.destinationSheetId} (${destRange})`,
+                },
+            ],
+            isError: false,
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error copying data: ${error.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}