mcp-gsheets 1.5.0 → 1.5.3

package/README.md

@@ -12,33 +12,122 @@
 ![Node](https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js&logoColor=white)
 ![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?logo=prettier&logoColor=white)
 
-A Model Context Protocol (MCP) server for Google Sheets API integration. Enables reading, writing, and managing Google Sheets documents directly from your MCP client (e.g., Claude Desktop).
+A Model Context Protocol (MCP) server for Google Sheets API integration. Enables reading, writing, and managing Google Sheets documents directly from your MCP client (e.g., Claude Code, Claude Desktop, Cursor, etc.).
 
-## 🚀 Quick Start
+## Key Features
 
-### 1. Prerequisites
+- **Complete Google Sheets Integration**: Read, write, and manage spreadsheets
+- **Advanced Operations**: Batch operations, formatting, charts, and conditional formatting
+- **Flexible Authentication**: Support for both file-based and JSON string credentials
+- **Production Ready**: Built with TypeScript, comprehensive error handling, and full test coverage
 
-- Node.js v18 or higher
-- Google Cloud Project with Sheets API enabled
+## Requirements
+
+- [Node.js](https://nodejs.org/) v18 or higher
+- [Google Cloud Project](https://console.cloud.google.com) with Sheets API enabled
 - Service Account with JSON key file
+- [npm](https://www.npmjs.com/)
+
+## Getting Started
+
+### Quick Install (Recommended)
+
+Add the following config to your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "mcp-gsheets": {
+      "command": "npx",
+      "args": ["-y", "mcp-gsheets@latest"],
+      "env": {
+        "GOOGLE_PROJECT_ID": "your-project-id",
+        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
+      }
+    }
+  }
+}
+```
 
-### 2. Installation
+> [!NOTE]
+> Using `mcp-gsheets@latest` ensures that your MCP client will always use the latest version of the MCP Google Sheets server.
+
+### MCP Client Configuration
+
+<details>
+  <summary>Claude Code</summary>
+  Use the Claude Code CLI to add the MCP Google Sheets server (<a href="https://docs.anthropic.com/en/docs/claude-code/mcp">guide</a>):
 
 ```bash
-# Clone the repository
-git clone https://github.com/freema/mcp-gsheets.git
-# Or using SSH
-# git clone git@github.com:freema/mcp-gsheets.git
-cd mcp-gsheets
+claude mcp add mcp-gsheets npx mcp-gsheets@latest
+```
 
-# Install dependencies
-npm install
+After adding, edit your Claude Code config to add the required environment variables:
 
-# Build the project
-npm run build
+```json
+{
+  "mcpServers": {
+    "mcp-gsheets": {
+      "command": "npx",
+      "args": ["mcp-gsheets@latest"],
+      "env": {
+        "GOOGLE_PROJECT_ID": "your-project-id",
+        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+  <summary>Claude Desktop</summary>
+
+Add to your Claude Desktop config:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "mcp-gsheets": {
+      "command": "npx",
+      "args": ["-y", "mcp-gsheets@latest"],
+      "env": {
+        "GOOGLE_PROJECT_ID": "your-project-id",
+        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
+      }
+    }
+  }
+}
 ```
 
-### 3. Google Cloud Setup
+</details>
+
+<details>
+  <summary>Cursor</summary>
+
+Go to `Cursor Settings` → `MCP` → `New MCP Server`. Use the config provided above.
+
+</details>
+
+<details>
+  <summary>Cline</summary>
+
+Follow https://docs.cline.bot/mcp/configuring-mcp-servers and use the config provided above.
+
+</details>
+
+<details>
+  <summary>Other MCP Clients</summary>
+
+For other MCP clients, use the standard configuration format shown above. Ensure the `command` is set to `npx` and include the environment variables for Google Cloud authentication.
+
+</details>
+
+### Google Cloud Setup
 
 1. Go to [Google Cloud Console](https://console.cloud.google.com)
 2. Create a new project or select existing
@@ -54,48 +143,92 @@ npm run build
    - Click Share and add the service account email (from JSON file)
    - Grant "Editor" permissions
 
-### 4. Configure MCP Client
+### Alternative Authentication Methods
 
-#### Easy Setup (Recommended)
+#### Option 1: JSON String Authentication
 
-Run the interactive setup script:
+Instead of using a file path for credentials, you can provide the service account credentials directly as a JSON string. This is useful for containerized environments, CI/CD pipelines, or when you want to avoid managing credential files.
 
-```bash
-npm run setup
+```json
+{
+  "mcpServers": {
+    "mcp-gsheets": {
+      "command": "npx",
+      "args": ["-y", "mcp-gsheets@latest"],
+      "env": {
+        "GOOGLE_PROJECT_ID": "your-project-id",
+        "GOOGLE_SERVICE_ACCOUNT_KEY": "{\"type\":\"service_account\",\"project_id\":\"your-project\",\"private_key_id\":\"...\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n\",\"client_email\":\"...@....iam.gserviceaccount.com\",\"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\":\"...\"}"
+      }
+    }
+  }
+}
 ```
 
-This will:
-- Guide you through the configuration
-- Automatically detect your Node.js installation (including nvm)
-- Find your Claude Desktop config
-- Create the proper JSON configuration
-- Optionally create a .env file for development
+**Note**: When using `GOOGLE_SERVICE_ACCOUNT_KEY`:
+- The entire JSON must be on a single line
+- All quotes must be escaped with backslashes
+- Newlines in the private key must be represented as `\\n`
+- If the JSON includes a `project_id`, you can omit `GOOGLE_PROJECT_ID`
 
-#### Manual Setup
+#### Option 2: Private Key Authentication (Simplified)
 
-If you prefer manual configuration, add to your Claude Desktop config:
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-- Linux: `~/.config/claude/claude_desktop_config.json`
+For the most user-friendly approach, you can provide just the private key and email directly. This is the simplest method and requires only two fields from your service account JSON:
 
 ```json
 {
   "mcpServers": {
     "mcp-gsheets": {
-      "command": "node",
-      "args": ["/absolute/path/to/mcp-gsheets/dist/index.js"],
+      "command": "npx",
+      "args": ["-y", "mcp-gsheets@latest"],
       "env": {
-        "GOOGLE_PROJECT_ID": "your-project-id",
-        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
+        "GOOGLE_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCgR6bvMNOUHZ29\\n+YgbVHAXsT/s+L/jnXTCB193zikCzspSBSfxLu8VRDjkNq9WUoDxizTATzMFNvNf\\n...\\n-----END PRIVATE KEY-----\\n",
+        "GOOGLE_CLIENT_EMAIL": "spreadsheet@your-project.iam.gserviceaccount.com"
       }
     }
   }
 }
 ```
 
-#### Alternative: JSON String Authentication
+**Note**: When using `GOOGLE_PRIVATE_KEY`:
+- Newlines in the private key should be represented as `\\n`
+- The private key must include the `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----` markers
+- The client email should be the service account email from your JSON file
+- `GOOGLE_PROJECT_ID` is optional when using this method
 
-Instead of using a file path, you can provide the service account credentials directly as a JSON string. This is useful for containerized environments, CI/CD pipelines, or when you want to avoid managing credential files.
+## Local Development Setup
+
+If you want to develop or contribute to this project, you can clone and build it locally:
+
+```bash
+# Clone the repository
+git clone https://github.com/freema/mcp-gsheets.git
+cd mcp-gsheets
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+```
+
+### Interactive Setup Script
+
+Run the interactive setup script to configure your local MCP client:
+
+```bash
+npm run setup
+```
+
+This will:
+- Guide you through the configuration
+- Automatically detect your Node.js installation (including nvm)
+- Find your Claude Desktop config
+- Create the proper JSON configuration
+- Optionally create a .env file for development
+
+### Manual Local Configuration
+
+If you prefer manual configuration with a local build, add to your MCP client config:
 
 ```json
 {
@@ -105,21 +238,13 @@ Instead of using a file path, you can provide the service account credentials di
       "args": ["/absolute/path/to/mcp-gsheets/dist/index.js"],
       "env": {
         "GOOGLE_PROJECT_ID": "your-project-id",
-        "GOOGLE_SERVICE_ACCOUNT_KEY": "{\"type\":\"service_account\",\"project_id\":\"your-project\",\"private_key_id\":\"...\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n\",\"client_email\":\"...@....iam.gserviceaccount.com\",\"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\":\"...\"}"
+        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
       }
     }
   }
 }
 ```
 
-**Note**: When using `GOOGLE_SERVICE_ACCOUNT_KEY`:
-- The entire JSON must be on a single line
-- All quotes must be escaped with backslashes
-- Newlines in the private key must be represented as `\\n`
-- If the JSON includes a `project_id`, you can omit `GOOGLE_PROJECT_ID`
-
-Restart Claude Desktop after adding the configuration.
-
 ## 📦 Build & Development
 
 ### Development Commands
@@ -258,7 +383,9 @@ npm run typecheck
 **"Authentication failed"**
 - If using file-based auth: Verify JSON key path is absolute and correct
 - If using JSON string auth: Ensure JSON is properly escaped and valid
-- Check GOOGLE_PROJECT_ID matches your project (or is included in JSON)
+- If using private key auth: Check that the private key includes BEGIN/END markers and newlines are escaped as `\\n`
+- Verify GOOGLE_CLIENT_EMAIL is a valid service account email
+- Check GOOGLE_PROJECT_ID matches your project (or is included in JSON for full JSON auth)
 - Ensure Sheets API is enabled
 
 **"Permission denied"**

package/dist/index.js

@@ -12336,6 +12336,13 @@ async function getAuthClient() {
           "Failed to parse GOOGLE_SERVICE_ACCOUNT_KEY: Invalid JSON format. Please ensure the environment variable contains valid JSON."
         );
       }
+    } else if (process.env.GOOGLE_PRIVATE_KEY && process.env.GOOGLE_CLIENT_EMAIL) {
+      const credentials = {
+        type: "service_account",
+        private_key: process.env.GOOGLE_PRIVATE_KEY.replace(/\\n/g, "\n"),
+        client_email: process.env.GOOGLE_CLIENT_EMAIL
+      };
+      options.credentials = credentials;
     }
     authClient = new GoogleAuth(options);
   }
@@ -12353,12 +12360,35 @@ async function getAuthenticatedClient() {
   return sheetsClient;
 }
 function validateAuth() {
-  if (!process.env.GOOGLE_APPLICATION_CREDENTIALS && !process.env.GOOGLE_SERVICE_ACCOUNT_KEY) {
+  const hasFileAuth = !!process.env.GOOGLE_APPLICATION_CREDENTIALS;
+  const hasJsonAuth = !!process.env.GOOGLE_SERVICE_ACCOUNT_KEY;
+  const hasPrivateKeyAuth = !!process.env.GOOGLE_PRIVATE_KEY && !!process.env.GOOGLE_CLIENT_EMAIL;
+  if (!hasFileAuth && !hasJsonAuth && !hasPrivateKeyAuth) {
     throw new Error(
-      "No authentication method provided. Please set either:\n- GOOGLE_APPLICATION_CREDENTIALS to the path of your service account key file, or\n- GOOGLE_SERVICE_ACCOUNT_KEY to the JSON string of your service account credentials."
+      "No authentication method provided. Please set one of:\n- GOOGLE_APPLICATION_CREDENTIALS to the path of your service account key file\n- GOOGLE_SERVICE_ACCOUNT_KEY to the JSON string of your service account credentials\n- GOOGLE_PRIVATE_KEY and GOOGLE_CLIENT_EMAIL for direct private key authentication"
     );
   }
-  if (!process.env.GOOGLE_APPLICATION_CREDENTIALS && process.env.GOOGLE_SERVICE_ACCOUNT_KEY) {
+  if (!hasFileAuth && !hasJsonAuth && hasPrivateKeyAuth) {
+    if (!process.env.GOOGLE_PRIVATE_KEY) {
+      throw new Error("GOOGLE_PRIVATE_KEY is required when using private key authentication");
+    }
+    if (!process.env.GOOGLE_CLIENT_EMAIL) {
+      throw new Error("GOOGLE_CLIENT_EMAIL is required when using private key authentication");
+    }
+    const privateKey = process.env.GOOGLE_PRIVATE_KEY.replace(/\\n/g, "\n");
+    if (!privateKey.includes("BEGIN PRIVATE KEY") || !privateKey.includes("END PRIVATE KEY")) {
+      throw new Error(
+        "GOOGLE_PRIVATE_KEY appears to be invalid. It should start with -----BEGIN PRIVATE KEY----- and end with -----END PRIVATE KEY-----"
+      );
+    }
+    const emailRegex2 = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    if (!emailRegex2.test(process.env.GOOGLE_CLIENT_EMAIL)) {
+      throw new Error(
+        "GOOGLE_CLIENT_EMAIL appears to be invalid. It should be a valid email address (e.g., your-service-account@your-project.iam.gserviceaccount.com)"
+      );
+    }
+  }
+  if (!hasFileAuth && hasJsonAuth) {
     try {
       const credentials = JSON.parse(process.env.GOOGLE_SERVICE_ACCOUNT_KEY);
       if (!credentials.type || credentials.type !== "service_account") {
@@ -12382,7 +12412,7 @@ function validateAuth() {
       throw error;
     }
   }
-  if (!process.env.GOOGLE_PROJECT_ID) {
+  if (!process.env.GOOGLE_PROJECT_ID && !hasPrivateKeyAuth) {
     throw new Error(
       "GOOGLE_PROJECT_ID environment variable is not set. Please set it to your Google Cloud project ID, or ensure it is included in your service account credentials."
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-gsheets",
-  "version": "1.5.0",
+  "version": "1.5.3",
   "description": "Model Context Protocol (MCP) server for Google Sheets API integration",
   "author": "freema",
   "license": "MIT",