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.
- Authentication
- Service-Account via base64-encoded
CREDENTIALS_CONFIG - OAuth2 using
credentials.json+token.jsonfor user-scoped access
- Service-Account via base64-encoded
- 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).
- 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 (downloadservice_account.json)
- (Optional) A Drive folder ID if you want new sheets moved out of My Drive
- Clone the repo
git clone https://github.com/yourusername/mcp-google-sheets.git cd mcp-google-sheets - Install dependencies
bun install- 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')bun index.tsOn 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.
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.
Clone & configure as above.
Start the server:
bun index.ts
Invoke a tool via ClaudeFeel free to open issues or PRs for new tools, bug fixes, and enhancements.