google-sheet-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MUST Dev
+
+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,210 @@
+# Google Sheets MCP Server
+
+Connect Google Sheets to Cursor, VS Code, Claude Code and AI agents — **in 3 minutes**.
+
+> Your spreadsheet becomes a data source that AI agents can read, write, and query.
+
+## 🎯 What is this?
+
+A **Model Context Protocol (MCP) server** that lets AI coding agents (Cursor, Copilot, Claude, Codex) interact with Google Sheets as a database.
+
+Once configured, you can tell your AI agent:
+
+```
+"Read all users from the Users sheet"
+"Add a new order row: name=Anton, total=150"
+"Update the status column for row 23"
+"List all sheets in my spreadsheet"
+```
+
+## ⚡ Quick Start
+
+Pick the auth method that fits your use case:
+
+### Service Account (recommended for team/automation)
+
+```bash
+npx google-sheet-mcp init
+```
+
+You'll need:
+- **Google Sheet URL** — paste your sheet link
+- **Service Account JSON key** — download from Google Cloud Console
+
+### Personal Account via OAuth2 (for personal sheets)
+
+Use when you want the AI to act **on your behalf** — access your private sheets without sharing them with a service account.
+
+```bash
+npx google-sheet-mcp init --auth oauth
+```
+
+You'll go through a browser-based OAuth2 flow. A refresh token is saved and **auto-refreshed** — you never need to re-login.
+
+> **📖 [When to use OAuth2 →](docs/setup-oauth2.md)** — detailed guide and scenarios.
+
+### 2. Connect your IDE
+
+Add to **`.cursor/mcp.json`** (Cursor):
+
+```json
+{
+  "mcpServers": {
+    "google-sheets": {
+      "command": "npx",
+      "args": ["google-sheet-mcp"]
+    }
+  }
+}
+```
+
+Or **`.vscode/mcp.json`** (VS Code):
+
+```json
+{
+  "servers": {
+    "google-sheets": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["google-sheet-mcp"]
+    }
+  }
+}
+```
+
+More configs: [`examples/`](examples/) — Cursor, VS Code, Claude, Codex.
+
+### 3. Restart your IDE
+
+That's it. Your AI agent now has access to your Google Sheet.
+
+## 🛠 CLI Commands
+
+| Command | Description |
+|---------|------------|
+| `npx google-sheet-mcp init` | Interactive setup wizard (service account) |
+| `npx google-sheet-mcp init --auth oauth` | Setup with personal Google account (OAuth2) |
+| `npx google-sheet-mcp test` | Test connection + list sheets |
+| `npx google-sheet-mcp token-status` | Check OAuth2 refresh token health |
+| `npx google-sheet-mcp list` | List all sheets in the spreadsheet |
+| `npx google-sheet-mcp read -s <name>` | Read data from a sheet |
+| `npx google-sheet-mcp create -s <name>` | Create a new sheet tab |
+| `npx google-sheet-mcp append -s <name> -d '{"col":"val"}'` | Append a row |
+| `npx google-sheet-mcp config` | Show current configuration |
+
+## 🧠 MCP Tools (for AI Agents)
+
+Once connected, AI agents get these tools:
+
+| Tool | What it does |
+|------|-------------|
+| `sheets_list_tabs` | List all sheet tabs with row/column counts |
+| `sheets_read_range` | Read data from a range (returns objects with header keys) |
+| `sheets_get_sheet` | Get spreadsheet metadata (title, URL, locale) |
+| `sheets_write_range` | Write a 2D array of values to a range |
+| `sheets_create_tab` | Create a new sheet tab |
+| `sheets_append_row` | Append a row (auto-aligns with headers) |
+
+## 🔐 Prerequisites
+
+### Google Cloud Setup (3 min)
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a project (or use existing)
+3. **Enable Sheets API**: APIs & Services → Library → "Google Sheets API" → Enable
+4. **Create Service Account**: APIs & Services → Credentials → Create Credentials → Service Account
+5. Give it a name → Create → Done
+6. Click the service account → Keys → Add Key → Create New Key → JSON → Download
+7. **Share your sheet**: Open your Google Sheet → Share → add the service account email (from the JSON) as **Editor**
+
+> 📖 Detailed guide with screenshots: [docs/setup-google.md](docs/setup-google.md)
+
+### OAuth2 Setup (for personal Google accounts)
+
+**When to use OAuth2 instead of Service Account:**
+
+- You want AI to access **your personal sheets** that you don't want to share with a service account
+- You're the only user and don't want to create a service account
+- Your sheets contain sensitive data that shouldn't be accessible via a shared key
+
+**Setup:**
+
+```bash
+npx google-sheet-mcp init --auth oauth
+```
+
+The wizard will:
+1. Ask for your OAuth2 Client ID and Client Secret (from Google Cloud Console)
+2. Open a browser for you to grant access
+3. Capture the authorization code automatically
+4. Exchange it for a **refresh token** (stored locally)
+
+**How refresh tokens work:**
+
+- The refresh token is stored in `.google-sheet-mcp.json`
+- Access tokens are **auto-refreshed** by googleapis — you never need to re-login
+- If a token becomes invalid, just run `npx google-sheet-mcp init --auth oauth` to replace it
+
+**Check token health:**
+
+```bash
+npx google-sheet-mcp token-status
+```
+
+> 🔑 **Key benefit:** The AI agent acts as *you* — it accesses exactly the sheets you have access to. No need to share sheets with a service account email.
+
+> 📖 Detailed guide: [docs/setup-oauth2.md](docs/setup-oauth2.md)
+
+## 📁 Configuration
+
+Config is stored in `.google-sheet-mcp.json` (in your project or home directory):
+
+```json
+{
+  "spreadsheetId": "1ABC...xyz",
+  "credentialsPath": "./credentials.json",
+  "sheets": ["Users", "Orders", "Payments"]
+}
+```
+
+Or use environment variables:
+
+```bash
+export GOOGLE_SPREADSHEET_ID="1ABC...xyz"
+export GOOGLE_APPLICATION_CREDENTIALS="./credentials.json"
+```
+
+## 🏗 Architecture
+
+```
+google-sheet-mcp/
+├── src/
+│   ├── cli/              # CLI commands (init, test, list, read, append)
+│   ├── server/           # MCP stdio server + Google Sheets client
+│   └── config/           # Config loader (.google-sheet-mcp.json + env)
+├── examples/             # MCP configs for Cursor, VS Code, Claude, Codex
+├── docs/                 # Setup guides
+├── README.md
+└── package.json
+```
+
+## ❓ FAQ
+
+### Do I need to clone this repo?
+No. Just use `npx google-sheet-mcp init`. No installation required.
+
+### What permissions does the service account need?
+Only "Editor" on the specific spreadsheet. Not on your entire Google Drive.
+
+### Can I connect multiple sheets?
+Yes. Use different config files per project, or set env vars per spreadsheet.
+
+### Does it work with private sheets?
+Yes. Share the sheet with the service account email (found in the JSON key).
+
+### Is my data sent to a third party?
+No. The MCP server runs **locally** on your machine. Google Sheets API calls go directly from your machine to Google. No intermediate servers.
+
+## 📄 License
+
+MIT

package/docs/setup-google.md

@@ -0,0 +1,122 @@
+# Google Cloud Setup Guide
+
+> Step-by-step: Create a Service Account and enable Sheets API.
+
+⏱ **Time: ~3 minutes** (first time)
+
+---
+
+## Step 1: Create a Google Cloud Project
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Click the project dropdown (top-left, next to "Google Cloud")
+3. Click **NEW PROJECT**
+4. Name it (e.g., `my-sheets-mcp`) → **CREATE**
+
+> If you already have a project, skip to Step 2.
+
+---
+
+## Step 2: Enable Google Sheets API
+
+1. In your project, go to **APIs & Services** → **Library**
+2. Search for "Google Sheets API"
+3. Click on it → **ENABLE**
+
+> Wait a few seconds for the API to activate.
+
+---
+
+## Step 3: Create a Service Account
+
+1. Go to **APIs & Services** → **Credentials**
+2. Click **CREATE CREDENTIALS** → **Service Account**
+3. Fill in:
+   - **Service account name**: `sheets-mcp` (or any name)
+   - **Service account ID**: auto-filled
+   - **Description**: `Access for Google Sheet MCP server` (optional)
+4. Click **CREATE AND CONTINUE**
+5. Role: **Basic → Editor** (or skip — we only need sheet access, not project-wide)
+6. Click **DONE**
+
+---
+
+## Step 4: Download JSON Key
+
+1. In the Credentials page, find your service account under "Service Accounts"
+2. Click on its email address
+3. Go to **KEYS** tab
+4. Click **ADD KEY** → **Create New Key**
+5. Select **JSON** → **CREATE**
+
+The JSON file downloads automatically. Save it somewhere safe, e.g.:
+```
+~/my-project/credentials.json
+```
+
+> ⚠️ **Security:** This key gives access to any sheet shared with this account. Don't commit it to git. Add `credentials.json` to `.gitignore`.
+
+---
+
+## Step 5: Share Your Sheet with the Service Account
+
+1. Open the JSON key file you downloaded
+2. Find the `client_email` field (e.g., `sheets-mcp@my-project.iam.gserviceaccount.com`)
+3. Copy that email address
+4. Open your Google Sheet → click **Share** (top-right)
+5. Paste the email → set permission to **Editor**
+6. Click **Send** (or "Share anyway" if prompted)
+
+> **Why Editor?** The MCP server needs to both read and write. If you only need read access, **Viewer** is enough.
+
+---
+
+## Step 6: Test the Connection
+
+```bash
+npx google-sheet-mcp init
+```
+
+Paste your sheet URL and credentials path. The wizard will test the connection.
+
+Or manually:
+
+```bash
+export GOOGLE_SPREADSHEET_ID="1ABC...xyz"
+export GOOGLE_APPLICATION_CREDENTIALS="./credentials.json"
+npx google-sheet-mcp test
+```
+
+Expected output:
+
+```
+🔗 Google Sheet MCP — Connection Test
+
+✅ Connected to "My Spreadsheet"
+✓ Users (150 rows × 6 cols)
+✓ Orders (320 rows × 8 cols)
+
+✅ Connection OK — ready to use from AI agents!
+```
+
+---
+
+## Troubleshooting
+
+### "Credentials file not found"
+Make sure the path to the JSON file is correct. Use absolute path if unsure:
+```bash
+export GOOGLE_APPLICATION_CREDENTIALS="/Users/you/project/credentials.json"
+```
+
+### "Google Sheets API has not been used in project"
+The Sheets API is not enabled. Go back to Step 2 and click **ENABLE**.
+
+### "The caller does not have permission"
+The service account doesn't have access to the sheet. Go back to Step 5 and share the sheet with `client_email` from the JSON.
+
+### "Error: insufficient authentication scopes"
+The service account key might be for a different API. Make sure you downloaded the JSON key for the right service account.
+
+### Can I use the same key for multiple sheets?
+Yes. Share each sheet with the same `client_email` from the JSON key.

package/docs/setup-oauth2.md

@@ -0,0 +1,177 @@
+# OAuth2 Setup — Personal Google Account
+
+> Use OAuth2 when you want the AI to act **on your behalf** with your personal Google Sheets.
+
+⏱ **Time: ~5 minutes** (first time)
+
+---
+
+## When to use OAuth2 vs Service Account
+
+| Scenario | Use |
+|----------|-----|
+| Team/shared spreadsheet, automation | Service Account |
+| Your personal spreadsheet, AI assistant | **OAuth2** |
+| You don't want to share sheets with a robot email | **OAuth2** |
+| CI/CD pipeline, server-side automation | Service Account |
+| Quick prototype with your own data | **OAuth2** |
+
+**With OAuth2:**
+- The AI agent accesses sheets **as you** — exactly the sheets you have permission to
+- No need to "Share with service account email"
+- Token is personal — don't share your `.google-sheet-mcp.json` with others
+
+---
+
+## Step 1: Create OAuth2 Credentials in Google Cloud
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Select your project (or create a new one)
+3. **Enable Sheets API**: APIs & Services → Library → "Google Sheets API" → Enable
+4. Go to **APIs & Services** → **Credentials**
+5. Click **CREATE CREDENTIALS** → **OAuth client ID**
+6. Configure the consent screen if prompted:
+   - User Type: **External**
+   - App name: `Google Sheet MCP` (or any name)
+   - User support email: your email
+   - Developer contact email: your email
+   - Scopes: you can skip adding scopes manually (the app requests them at runtime)
+   - Add yourself as a test user
+7. Back to Create OAuth client ID:
+   - Application type: **Desktop app**
+   - Name: `google-sheet-mcp`
+8. Click **CREATE**
+9. Copy the **Client ID** and **Client Secret**
+
+---
+
+## Step 2: Run the OAuth2 Setup Wizard
+
+```bash
+npx google-sheet-mcp init --auth oauth
+```
+
+The wizard asks:
+- **Google Sheet URL** — paste your sheet link
+- **Client ID** — from Step 1
+- **Client Secret** — from Step 1
+
+Then it:
+1. Opens a browser URL for you (or prints it)
+2. You sign in with your Google account
+3. You grant access to Google Sheets
+4. The authorization code is captured automatically
+5. Tokens are saved
+
+---
+
+## Step 3: What Happens Under the Hood
+
+```
+┌──────────────┐     ┌─────────────┐     ┌──────────────┐
+│   Your       │     │   Google    │     │   Google     │
+│   Terminal   │────▶│   OAuth2    │────▶│   Sheets     │
+│   (CLI)      │     │   Server    │     │   API        │
+└──────────────┘     └─────────────┘     └──────────────┘
+       │                    │                    │
+       │  1. Open URL       │                    │
+       │──────────────────▶ │                    │
+       │  2. You login      │                    │
+       │     & grant access  │                    │
+       │  3. Auth code       │                    │
+       │◀────────────────── │                    │
+       │                    │  4. Exchange code  │
+       │                    │     for tokens      │
+       │                    │──────────────────▶ │
+       │                    │  5. Refresh token   │
+       │                    │◀────────────────── │
+       │                    │                    │
+       │  6. Refresh token  │                    │
+       │  saved to config   │                    │
+       │◀────────────────── │                    │
+       │                    │                    │
+       │  Every API call:   │                    │
+       │  refresh token     │                    │
+       │  → fresh access    │                    │
+       │    token (auto)    │                    │
+```
+
+---
+
+## Token Auto-Refresh
+
+You never need to re-login. The `googleapis` library automatically:
+
+1. Sends the stored `refresh_token`
+2. Gets a fresh `access_token` (valid for 1 hour)
+3. Uses the `access_token` for API calls
+4. When `access_token` expires, repeats from step 1
+
+### Check Token Health
+
+```bash
+npx google-sheet-mcp token-status
+```
+
+Expected output:
+
+```
+🔑 Google Sheet MCP — Token Status
+
+  Config source: local
+  Auth type:     oauth2
+
+Stored token:
+  Status:       configured
+  Client ID:    123456789012-...
+  Refresh:      1//09BY_K6-BZ...
+
+  ✔ Token is valid
+  Access token expires: 2026-06-12T16:00:00.000Z
+  Scopes: https://www.googleapis.com/auth/spreadsheets
+
+✅ Refresh token is healthy
+  AI agents can now access your Google Sheets on your behalf.
+```
+
+---
+
+## Replacing an Invalid Token
+
+If the refresh token is revoked or expired:
+
+```bash
+npx google-sheet-mcp init --auth oauth
+```
+
+This walks you through the OAuth flow again and saves a new refresh token. No need to delete config files manually.
+
+---
+
+## Troubleshooting
+
+### "Access blocked: This app's request is invalid"
+Your OAuth consent screen may not be published. Go to Google Cloud Console → APIs & Services → OAuth consent screen → add yourself as a test user.
+
+### "No refresh token returned"
+Make sure `access_type=offline` is set (the CLI does this automatically). Try again and make sure to **approve all permissions**.
+
+### "Token is invalid" (token-status)
+The refresh token may have been revoked:
+1. Go to [Google Account Permissions](https://myaccount.google.com/permissions)
+2. Find "Google Sheet MCP"
+3. Remove it
+4. Run `npx google-sheet-mcp init --auth oauth` again
+
+### "Request had insufficient authentication scopes"
+You may have not granted the `spreadsheets` scope during OAuth. Remove the app from your Google Account permissions and re-authorize.
+
+---
+
+## Security Notes
+
+- 🔒 The refresh token is stored in `.google-sheet-mcp.json` — **don't commit this file**
+- 🔒 Add `.google-sheet-mcp.json` to `.gitignore`
+- 🔒 The token grants access to **all your Google Sheets** — treat it like a password
+- 🔒 You can revoke access anytime: [Google Account Permissions](https://myaccount.google.com/permissions)
+- 🔒 For team usage, prefer Service Accounts

package/examples/claude-mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "google-sheets": {
+      "command": "npx",
+      "args": ["google-sheet-mcp"],
+      "env": {
+        "GOOGLE_SPREADSHEET_ID": "<your-spreadsheet-id>",
+        "GOOGLE_APPLICATION_CREDENTIALS": "./credentials.json"
+      }
+    }
+  }
+}

package/examples/codex-mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "google-sheets": {
+      "command": "npx",
+      "args": ["-y", "google-sheet-mcp"],
+      "env": {
+        "GOOGLE_SPREADSHEET_ID": "<your-spreadsheet-id>",
+        "GOOGLE_APPLICATION_CREDENTIALS": "./credentials.json"
+      }
+    }
+  }
+}

package/examples/cursor-mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "google-sheets": {
+      "command": "npx",
+      "args": ["google-sheet-mcp"],
+      "env": {
+        "GOOGLE_SPREADSHEET_ID": "<your-spreadsheet-id>",
+        "GOOGLE_APPLICATION_CREDENTIALS": "./credentials.json"
+      }
+    }
+  }
+}

package/examples/vscode-mcp.json

@@ -0,0 +1,13 @@
+{
+  "servers": {
+    "google-sheets": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["google-sheet-mcp"],
+      "env": {
+        "GOOGLE_SPREADSHEET_ID": "<your-spreadsheet-id>",
+        "GOOGLE_APPLICATION_CREDENTIALS": "./credentials.json"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "google-sheet-mcp",
+  "version": "1.0.0",
+  "description": "Connect Google Sheets to Cursor, VS Code, Claude Code and AI agents in 3 minutes. MCP Server + CLI installer.",
+  "keywords": [
+    "google-sheets",
+    "mcp",
+    "model-context-protocol",
+    "cursor",
+    "vscode",
+    "claude",
+    "ai-agent",
+    "spreadsheet",
+    "data-source"
+  ],
+  "license": "MIT",
+  "author": "MUST Dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/we2go/google-mcp.git"
+  },
+  "type": "module",
+  "main": "./src/server/server.mjs",
+  "bin": {
+    "google-sheet-mcp": "src/cli/cli.mjs"
+  },
+  "files": [
+    "src/",
+    "examples/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/server/server.mjs",
+    "init": "node src/cli/cli.mjs init",
+    "test": "node src/cli/cli.mjs test",
+    "list": "node src/cli/cli.mjs list",
+    "read": "node src/cli/cli.mjs read",
+    "prepublishOnly": "echo 'Ready to publish'"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.0",
+    "commander": "^13.1.0",
+    "googleapis": "^148.0.0",
+    "chalk": "^5.4.1",
+    "ora": "^8.2.0",
+    "inquirer": "^12.5.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}