mcp-google-sheets-full AGENTS.md

AGENTS.md

Instructions for AI agents (Claude Code, Cursor, etc.) installing or operating mcp-google-sheets-full on behalf of a user. Imperative, no marketing. Read top-to-bottom on first contact.

Install + register (idempotent)

npm install -g mcp-google-sheets-full
claude mcp add google-sheets -- mcp-google-sheets-full --scope user

Replace the second line with the equivalent for the current MCP client (Cursor: edit mcp.json; Claude Desktop: edit claude_desktop_config.json). After registering, ask the user to restart the MCP client so the server is loaded.

First call: detect setup state

Always call auth_status first when starting a session against this server. It tells you which auth mode is active and what is missing.

OAuth mode response (default):

{
  "auth_mode": "oauth",
  "configDir": "C:\\Users\\<user>\\.mcp-google-sheets",
  "credentialsPath": ".../gdrive-credentials.json",
  "tokenPath": ".../gdrive-token.json",
  "service_account_key_path": null,
  "credentials_present": true|false,
  "token_present": true|false
}

• credentials_present: false → go to OAuth setup below.
• credentials_present: true, token_present: false → go to First OAuth authorization below.
• Both true → ready to operate.

Service account mode response (env GOOGLE_APPLICATION_CREDENTIALS set):

{
  "auth_mode": "service_account",
  "service_account_key_path": "/path/to/sa-key.json",
  "service_account_key_present": true|false,
  "service_account_email": "[email protected]"
}

• service_account_key_present: false → the env var points at a missing file. Tell the user the path and ask them to fix it.
• service_account_key_present: true → ready to operate, but every spreadsheet must be shared with service_account_email (Editor or Viewer). If a tool call returns 403, that's the cause.

Auth mode selection

Do not prompt the user to pick a mode. The mode is determined automatically by whether GOOGLE_APPLICATION_CREDENTIALS is set in the server's process env: