mcp-gsheets 1.4.3 → 1.5.2

package/README.md

@@ -12,68 +12,79 @@
 ![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/)
 
-### 2. Installation
+## Getting Started
 
-```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
+### Quick Install (Recommended)
 
-# Install dependencies
-npm install
+Add the following config to your MCP client:
 
-# Build the project
-npm run build
+```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
+> [!NOTE]
+> Using `mcp-gsheets@latest` ensures that your MCP client will always use the latest version of the MCP Google Sheets server.
 
-1. Go to [Google Cloud Console](https://console.cloud.google.com)
-2. Create a new project or select existing
-3. Enable Google Sheets API:
-   - Navigate to "APIs & Services" → "Library"
-   - Search for "Google Sheets API" and click "Enable"
-4. Create Service Account:
-   - Go to "APIs & Services" → "Credentials"
-   - Click "Create Credentials" → "Service Account"
-   - Download the JSON key file
-5. Share your spreadsheets:
-   - Open your Google Sheet
-   - Click Share and add the service account email (from JSON file)
-   - Grant "Editor" permissions
+### MCP Client Configuration
 
-### 4. Configure MCP Client
+<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>):
 
-#### Easy Setup (Recommended)
+```bash
+claude mcp add mcp-gsheets npx mcp-gsheets@latest
+```
 
-Run the interactive setup script:
+After adding, edit your Claude Code config to add the required environment variables:
 
-```bash
-npm run setup
+```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"
+      }
+    }
+  }
+}
 ```
 
-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
+</details>
 
-#### Manual Setup
+<details>
+  <summary>Claude Desktop</summary>
 
-If you prefer manual configuration, add to your Claude Desktop config:
+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`
@@ -82,8 +93,8 @@ If you prefer manual configuration, add to your Claude Desktop config:
 {
   "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"
@@ -93,16 +104,55 @@ If you prefer manual configuration, add to your Claude Desktop config:
 }
 ```
 
-#### Alternative: JSON String Authentication
+</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
+3. Enable Google Sheets API:
+   - Navigate to "APIs & Services" → "Library"
+   - Search for "Google Sheets API" and click "Enable"
+4. Create Service Account:
+   - Go to "APIs & Services" → "Credentials"
+   - Click "Create Credentials" → "Service Account"
+   - Download the JSON key file
+5. Share your spreadsheets:
+   - Open your Google Sheet
+   - Click Share and add the service account email (from JSON file)
+   - Grant "Editor" permissions
+
+### Alternative: JSON String Authentication
 
-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.
+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.
 
 ```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_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\":\"...\"}"
@@ -118,7 +168,55 @@ Instead of using a file path, you can provide the service account credentials di
 - 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.
+## 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
+{
+  "mcpServers": {
+    "mcp-gsheets": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-gsheets/dist/index.js"],
+      "env": {
+        "GOOGLE_PROJECT_ID": "your-project-id",
+        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
+      }
+    }
+  }
+}
+```
 
 ## 📦 Build & Development
 
@@ -195,8 +293,9 @@ npm run dev  # Watch mode with auto-reload
 ### Writing Data
 - `sheets_update_values` - Write to a range
 - `sheets_batch_update_values` - Write to multiple ranges
-- `sheets_append_values` - Append rows to a table
+- `sheets_append_values` - Append rows to a table (**Note:** Default `insertDataOption` is `OVERWRITE`. To insert new rows, set `insertDataOption: 'INSERT_ROWS'`)
 - `sheets_clear_values` - Clear cell contents
+- `sheets_insert_rows` - Insert new rows at specific position with optional data
 
 ### Sheet Management
 - `sheets_insert_sheet` - Add new sheet
@@ -295,6 +394,44 @@ Use `sheets_get_metadata` to list all sheets with their IDs.
 4. Check rate limits for large operations
 5. Use `sheets_check_access` to verify permissions before operations
 
+## 📘 Tool Details
+
+### sheets_insert_rows
+
+Insert new rows at a specific position in a spreadsheet with optional data.
+
+**Parameters:**
+- `spreadsheetId` (required): The ID of the spreadsheet
+- `range` (required): A1 notation anchor point where rows will be inserted (e.g., "Sheet1!A5")
+- `rows` (optional): Number of rows to insert (default: 1)
+- `position` (optional): 'BEFORE' or 'AFTER' the anchor row (default: 'BEFORE')
+- `inheritFromBefore` (optional): Whether to inherit formatting from the row before (default: false)
+- `values` (optional): 2D array of values to fill the newly inserted rows
+- `valueInputOption` (optional): 'RAW' or 'USER_ENTERED' (default: 'USER_ENTERED')
+
+**Examples:**
+
+```javascript
+// Insert 1 empty row before row 5
+{
+  "spreadsheetId": "your-spreadsheet-id",
+  "range": "Sheet1!A5"
+}
+
+// Insert 3 rows after row 10 with data
+{
+  "spreadsheetId": "your-spreadsheet-id",
+  "range": "Sheet1!A10",
+  "rows": 3,
+  "position": "AFTER",
+  "values": [
+    ["John", "Doe", "john@example.com"],
+    ["Jane", "Smith", "jane@example.com"],
+    ["Bob", "Johnson", "bob@example.com"]
+  ]
+}
+```
+
 ## 📋 Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for a list of changes in each version.

package/dist/index.js

@@ -12624,6 +12624,14 @@ function validateSpreadsheetIdField(id) {
     throw new Error("Invalid spreadsheet ID format");
   }
 }
+function validateRangeField(range) {
+  if (!range || typeof range !== "string") {
+    throw new Error(ERROR_MESSAGES.RANGE_REQUIRED);
+  }
+  if (!validateRange(range)) {
+    throw new Error(ERROR_MESSAGES.INVALID_RANGE);
+  }
+}
 function validateSheetIdField(sheetId) {
   if (sheetId === void 0 || typeof sheetId !== "number") {
     throw new Error(ERROR_MESSAGES.SHEET_ID_REQUIRED);
@@ -12940,6 +12948,34 @@ function validateDeleteChartInput(input) {
     chartId: input.chartId
   };
 }
+function validateInsertRowsInput(input) {
+  validateSpreadsheetIdField(input.spreadsheetId);
+  validateRangeField(input.range);
+  const rows = input.rows ?? 1;
+  if (typeof rows !== "number" || rows <= 0) {
+    throw new Error("Rows must be a positive number");
+  }
+  const position = input.position ?? "BEFORE";
+  if (!["BEFORE", "AFTER"].includes(position)) {
+    throw new Error("Position must be either BEFORE or AFTER");
+  }
+  const inheritFromBefore = input.inheritFromBefore ?? false;
+  const valueInputOption = input.valueInputOption ?? "USER_ENTERED";
+  if (input.values) {
+    if (!Array.isArray(input.values) || !input.values.every((row) => Array.isArray(row))) {
+      throw new Error("Values must be a 2D array");
+    }
+  }
+  return {
+    spreadsheetId: input.spreadsheetId,
+    range: input.range,
+    rows,
+    position,
+    inheritFromBefore,
+    values: input.values,
+    valueInputOption
+  };
+}
 
 // src/utils/response-helpers.ts
 function createTextResponse(text) {
@@ -13162,7 +13198,7 @@ To fix this, either:
 // src/tools/append-values.ts
 var appendValuesTool = {
   name: "sheets_append_values",
-  description: "Append values to the end of a table in a Google Sheets spreadsheet",
+  description: 'Append values to the end of a table in a Google Sheets spreadsheet. IMPORTANT: By default, this will OVERWRITE existing empty cells. To INSERT new rows instead, set insertDataOption to "INSERT_ROWS".',
   inputSchema: {
     type: "object",
     properties: {
@@ -15566,6 +15602,122 @@ async function handleInsertDate(input) {
   }
 }
 
+// src/tools/insert-rows.ts
+var insertRowsTool = {
+  name: "sheets_insert_rows",
+  description: "Insert new rows at a specific position with optional data",
+  inputSchema: {
+    type: "object",
+    properties: {
+      spreadsheetId: {
+        type: "string",
+        description: "The ID of the spreadsheet (found in the URL after /d/)"
+      },
+      range: {
+        type: "string",
+        description: 'The A1 notation anchor point where rows will be inserted (e.g., "Sheet1!A5")'
+      },
+      rows: {
+        type: "number",
+        description: "Number of rows to insert (default: 1)"
+      },
+      position: {
+        type: "string",
+        enum: ["BEFORE", "AFTER"],
+        description: "Position relative to the anchor row (default: BEFORE)"
+      },
+      inheritFromBefore: {
+        type: "boolean",
+        description: "Whether to inherit formatting from the row before (default: false)"
+      },
+      values: {
+        type: "array",
+        items: {
+          type: "array"
+        },
+        description: "Optional 2D array of values to fill the newly inserted rows"
+      },
+      valueInputOption: {
+        type: "string",
+        enum: ["RAW", "USER_ENTERED"],
+        description: "How the input data should be interpreted (default: USER_ENTERED)"
+      }
+    },
+    required: ["spreadsheetId", "range"]
+  }
+};
+function indexToColumn(index) {
+  let column = "";
+  let num = index + 1;
+  while (num > 0) {
+    num--;
+    column = String.fromCharCode(num % 26 + "A".charCodeAt(0)) + column;
+    num = Math.floor(num / 26);
+  }
+  return column;
+}
+async function handleInsertRows(input) {
+  try {
+    const validatedInput = validateInsertRowsInput(input);
+    const sheets = await getAuthenticatedClient();
+    const { sheetName, range: cellRange } = extractSheetName(validatedInput.range);
+    const sheetId = await getSheetId(sheets, validatedInput.spreadsheetId, sheetName);
+    const parsedRange = parseRange(cellRange, sheetId);
+    const anchorRowIndex = parsedRange.startRowIndex ?? 0;
+    const anchorColumnIndex = parsedRange.startColumnIndex ?? 0;
+    const startIndex = validatedInput.position === "AFTER" ? anchorRowIndex + 1 : anchorRowIndex;
+    const endIndex = startIndex + validatedInput.rows;
+    const insertRequest = {
+      spreadsheetId: validatedInput.spreadsheetId,
+      requestBody: {
+        requests: [
+          {
+            insertDimension: {
+              range: {
+                sheetId,
+                dimension: "ROWS",
+                startIndex,
+                endIndex
+              },
+              inheritFromBefore: validatedInput.inheritFromBefore
+            }
+          }
+        ]
+      }
+    };
+    await sheets.spreadsheets.batchUpdate(insertRequest);
+    if (validatedInput.values && validatedInput.values.length > 0) {
+      const updateStartRow = startIndex + 1;
+      const updateEndRow = updateStartRow + validatedInput.values.length - 1;
+      const startColumn = indexToColumn(anchorColumnIndex);
+      const endColumn = indexToColumn(
+        anchorColumnIndex + Math.max(...validatedInput.values.map((row) => row.length)) - 1
+      );
+      const updateRange = sheetName ? `'${sheetName}'!${startColumn}${updateStartRow}:${endColumn}${updateEndRow}` : `${startColumn}${updateStartRow}:${endColumn}${updateEndRow}`;
+      await sheets.spreadsheets.values.update({
+        spreadsheetId: validatedInput.spreadsheetId,
+        range: updateRange,
+        valueInputOption: validatedInput.valueInputOption,
+        requestBody: {
+          values: validatedInput.values
+        }
+      });
+      const cellCount = validatedInput.values.reduce(
+        (sum, row) => sum + row.length,
+        0
+      );
+      return formatToolResponse(
+        `Inserted ${validatedInput.rows} rows ${validatedInput.position} row ${anchorRowIndex + 1} on "${sheetName || "Sheet"}" and updated ${cellCount} cells in range: ${updateRange}`
+      );
+    }
+    return formatToolResponse(
+      `Inserted ${validatedInput.rows} rows ${validatedInput.position} row ${anchorRowIndex + 1} on "${sheetName || "Sheet"}"`
+    );
+  } catch (error) {
+    return handleError(error);
+  }
+}
+
 // src/index.ts
 if (process.env.NODE_ENV !== "production") {
   try {
@@ -15607,7 +15759,9 @@ var toolHandlers = /* @__PURE__ */ new Map([
   ["sheets_delete_chart", handleDeleteChart],
   // Link and date operations
   ["sheets_insert_link", handleInsertLink],
-  ["sheets_insert_date", handleInsertDate]
+  ["sheets_insert_date", handleInsertDate],
+  // Row operations
+  ["sheets_insert_rows", handleInsertRows]
 ]);
 var allTools = [
   checkAccessTool,
@@ -15635,7 +15789,8 @@ var allTools = [
   updateChartTool,
   deleteChartTool,
   insertLinkTool,
-  insertDateTool
+  insertDateTool,
+  insertRowsTool
 ];
 async function main() {
   try {

package/package.json

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