google-sheets-mcp

# google-sheets-mcp

English | Korean

Local Model Context Protocol server for reading and writing Google Sheets through Google Sheets API v4.

This project is designed for local Codex/AI-agent workflows. It supports both service account credentials and OAuth user credentials.

Features

• Read spreadsheet metadata and worksheet tabs.

• Read values from A1 ranges.

• Update exact ranges.

• Append rows.

• Batch update multiple ranges.

• Clear values while preserving formatting.

• Report authentication status without exposing private keys or tokens.

Related MCP server: MCP Google Suite

MCP Tools

• auth_status

• get_spreadsheet

• list_worksheets

• read_range

• update_range

• append_rows

• batch_update_values

• clear_range

Install

npm.cmd install
npm.cmd run build

On macOS/Linux, use npm instead of npm.cmd.

Authentication: Service Account

Recommended for automation.

1. Create or choose a Google Cloud project.

2. Enable Google Sheets API.

3. Create a service account and download a JSON key.

4. Put the JSON key at:

secrets/google-service-account.json

5. Share each target spreadsheet with the service account email from the JSON key:

{
  "client_email": "your-service-account@your-project.iam.gserviceaccount.com"
}

Give Viewer access for read-only use or Editor access for writes.

The secrets/ directory is committed with only .gitkeep. All credential files inside it are ignored.

Authentication: Custom Credential Path

If you do not want credentials under the repository directory, create a local .env file:

GOOGLE_APPLICATION_CREDENTIALS=C:/secure/path/google-service-account.json

or provide inline JSON through a secret manager/environment variable:

GOOGLE_SERVICE_ACCOUNT_JSON={"type":"service_account",...}

Credential lookup order:

1. GOOGLE_APPLICATION_CREDENTIALS

2. GOOGLE_SERVICE_ACCOUNT_JSON

3. ./secrets/google-service-account.json

Authentication: OAuth User Account

Use OAuth when the MCP should act as your Google user account.

1. Create OAuth Client credentials in Google Cloud.

2. Add this redirect URI:

http://127.0.0.1:3333/oauth2callback

3. Create .env:

GOOGLE_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_CALLBACK_PORT=3333

4. Generate a refresh token:

npm.cmd run oauth:init

5. Open the printed URL, approve access, and add the printed refresh token to .env:

GOOGLE_OAUTH_REFRESH_TOKEN=your-refresh-token

Register With Codex

Build first:

npm.cmd run build

Then register the MCP server:

codex mcp add google-sheets-local -- node <path-to-google-sheets-mcp>/dist/index.js

Recommended ~/.codex/config.toml entry:

[mcp_servers.google-sheets-local]
command = "node"
args = ["<path-to-google-sheets-mcp>/dist/index.js"]
cwd = "<path-to-google-sheets-mcp>"

Restart Codex after changing MCP configuration or credentials.

Usage Notes

• Use auth_status first to verify the active authentication mode.

• Use list_worksheets before reading or writing ranges.

• For destructive operations, prefer reading the target range first.

• Use batch_update_values for large table edits to reduce Google API request count.

Security

Never commit credentials. The following are ignored by default:

• .env

• .env.* except .env.example

• credentials/

• secrets/* except secrets/.gitkeep

• *.service-account.json

• *.credentials.json

• *.token.json

License

MIT