Google Sheets

What is mcp-google-sheets?

mcp-google-sheets is a TypeScript-based Model Context Protocol (MCP) server that enables AI agents to securely interact with Google Sheets. It is built on Bun and the @modelcontextprotocol/sdk, supporting both OAuth2 and Service-Account authentication flows.

How to use mcp-google-sheets?

To use mcp-google-sheets, you need to have Bun (v1.0+) installed and a Google Cloud project with the Sheets API & Drive API enabled. You'll also need an OAuth2 Client ID or a Service Account key. After cloning the repository and installing dependencies, configure your environment by creating a .env file with your CREDENTIALS_CONFIG (base64-encoded service-account key JSON) or by placing credentials.json and token.json next to index.ts for OAuth2. You also need to provide the EMAIL_ID you'll use to access the spreadsheet and optionally a DRIVE_FOLDER_ID. Once configured, you can run the server using bun index.ts.

Key Features of mcp-google-sheets

• Authentication: Supports both Service-Account via base64-encoded CREDENTIALS_CONFIG and OAuth2 using credentials.json + token.json for user-scoped access.
• Comprehensive Toolset: Provides a wide range of tools for interacting with Google Sheets, including:
  • create: Creates a new spreadsheet.
  • listSheets: Lists all sheet tabs in a given spreadsheet.
  • renameSheet: Renames an existing sheet tab.
  • createSheet: Adds a new sheet tab to a spreadsheet.
  • spreadsheetInfo: Fetches metadata for a spreadsheet.
  • listSpreadsheets: Lists all spreadsheets in your configured Drive folder.
  • shareSpreadsheet: Shares a spreadsheet with users.
  • sheetData: Reads cell values from a sheet.
  • updateCells: Writes a 2D array of values into an A1-style range.
  • batchUpdate: Applies multiple range updates in a single request.
  • addRows / addColumns: Inserts rows or columns.
  • copySheet: Copies a sheet tab between spreadsheets.
• Bun Integration: Built on Bun for fast execution.
• Secure Interaction: Enables AI agents to securely interact with Google Sheets.
• Well-typed Tools: Provides well-typed "tools" for clear and reliable interactions.

Use Cases of mcp-google-sheets

mcp-google-sheets can be used in various scenarios where AI agents need to programmatically access and manipulate Google Sheets data. Some potential use cases include:

• Automated Data Entry: AI agents can automatically populate Google Sheets with data from various sources.
• Reporting and Analytics: AI agents can extract data from Google Sheets to generate reports or perform data analysis.
• Workflow Automation: Integrate Google Sheets operations into automated workflows managed by AI agents.
• Data Synchronization: Keep data in Google Sheets synchronized with other systems.
• Chatbot Integration: Allow chatbots to retrieve or update information in Google Sheets based on user queries.

FAQ from mcp-google-sheets

Q: What are the prerequisites for running mcp-google-sheets? A: You need Bun (v1.0+), a Google Cloud project with Sheets API & Drive API enabled, and either an OAuth2 Client ID or a Service Account key.

Q: How do I configure authentication? A: You can use a base64-encoded service-account key via CREDENTIALS_CONFIG in your .env file, or place credentials.json and token.json (generated after the first OAuth run) next to index.ts for OAuth2.

Q: How does the server work internally? A: It initializes the context by picking an authentication method, builds Google Sheets and Drive clients, and registers each tool via server.tool(...). It uses StdioServerTransport for tool invocation over stdin/stdout, and processes JSON requests from the agent to run handlers and return JSON-wrapped results.

Q: Can I contribute to the project? A: Yes, contributions for new tools, bug fixes, and enhancements are welcome via issues or PRs.

MCP-Google-Sheets

A TypeScript Model Context Protocol (MCP) server that lets AI agents securely interact with Google Sheets via well-typed “tools.” Built on Bun and the @modelcontextprotocol/sdk, it supports both OAuth2 and Service-Account flows.

---

🚀 Features

• Authentication
  • Service-Account via base64-encoded CREDENTIALS_CONFIG
  • OAuth2 using credentials.json + token.json for user-scoped access
• Tools
  • create
    Creates a new spreadsheet (and moves it into your Drive folder if configured).
  • listSheets
    Lists all sheet tabs in a given spreadsheet.
  • renameSheet
    Renames an existing sheet tab.
  • createSheet
    Adds a new sheet tab to a spreadsheet.
  • spreadsheetInfo
    Fetches metadata (title, sheet IDs, grid properties) for a spreadsheet.
  • listSpreadsheets
    Lists all spreadsheets in your configured Drive folder (or My Drive).
  • shareSpreadsheet
    Shares a spreadsheet with users (reader/commenter/writer) and sends notifications.
  • sheetData
    Reads cell values from a sheet and range (or whole sheet).
  • updateCells
    Writes a 2D array of values into an A1-style range.
  • batchUpdate
    Applies multiple range updates in a single request.
  • addRows / addColumns
    Inserts rows or columns at a specified index.
  • copySheet
    Copies a sheet tab between spreadsheets (optionally renaming it).

---

📋 Prerequisites

• Bun (v1.0+) installed and on your PATH
• A Google Cloud project with:
  • Sheets API & Drive API enabled
  • An OAuth2 Client ID (download credentials.json) or a Service Account key (download service_account.json)
• (Optional) A Drive folder ID if you want new sheets moved out of My Drive

---

⚙️ Setup

1. Clone the repo

   git clone https://github.com/yourusername/mcp-google-sheets.git
   cd mcp-google-sheets
   

2. Install dependencies

bun install

3. Configure environment

Create a .env (or export) with:

# Base64-encoded service-account key JSON (optional)
CREDENTIALS_CONFIG=BASE-64 ENCODED SERVICE_ACCOUNT.JSON


# Or put your OAuth2 JSON files next to index.ts:
#   credentials.json  (OAuth client secret)
#   token.json        (generated after first OAuth run)

# The google email address that you'll use to access the spreadsheet
EMAIL_ID="Enter the email address you’ll use to access the spreadsheet"
# (Optional) ID of the Drive folder to store new sheets
DRIVE_FOLDER_ID=1a2B3c4D5e6F...

Tip: On Linux/macOS you can do

export CREDENTIALS_CONFIG=$(base64 service_account.json | tr -d '\n')

▶️ Running the Server

bun index.ts

On first OAuth2 run (if using credentials.json), you’ll see a URL. Visit it, grant access, then paste the code back into your terminal. A token.json will be generated automatically.

🔧 How It Works

Initialization

• initContext() picks your auth method (Service-Account → OAuth2 → error).

• Builds google.sheets & google.drive clients and stores them in a shared context.

MCP Tool Registration

• Each “tool” (e.g. create, listSheets, sheetData) is registered via server.tool(...).

Transport

• Uses StdioServerTransport so Claude can invoke tools over stdin/stdout.

Invocation

The agent sends a JSON request:

{ "tool": "create", "args": { "title": "Budget Q2" } }

The server runs your handler, calls Google APIs, and returns JSON-wrapped results.

🛠️ Try It Out

Clone & configure as above.

Start the server:

bun index.ts
Invoke a tool via Claude

Demo

❤️ Contributing

Feel free to open issues or PRs for new tools, bug fixes, and enhancements.