Google Sheets MCP
English | Русский
接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
npx -y @a1-x-tech/[email protected]Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
GOOGLE_SHEETS_CLIENT_ID=<value> GOOGLE_SHEETS_CLIENT_SECRET=<secret> GOOGLE_SHEETS_REFRESH_TOKEN=<secret> GOOGLE_SHEETS_ACCESS_TOKEN=<secret> GOOGLE_SHEETS_OAUTH_PORT=<value> GOOGLE_SHEETS_API_BASE=<value> GOOGLE_SHEETS_TIMEOUT_MS=<value> GOOGLE_SHEETS_MAX_RETRIES=<value> claude mcp add io.github.a1-x-tech-mcp-google-sheets -- npx -y @a1-x-tech/mcp-google-sheets@1.1.2在終端機中執行。
{ "mcpServers": { "io.github.a1-x-tech-mcp-google-sheets": { "command": "npx", "args": [ "-y", "@a1-x-tech/[email protected]" ], "env": { "GOOGLE_SHEETS_CLIENT_ID": "<value>", "GOOGLE_SHEETS_CLIENT_SECRET": "<secret>", "GOOGLE_SHEETS_REFRESH_TOKEN": "<secret>", "GOOGLE_SHEETS_ACCESS_TOKEN": "<secret>", "GOOGLE_SHEETS_OAUTH_PORT": "<value>", "GOOGLE_SHEETS_API_BASE": "<value>", "GOOGLE_SHEETS_TIMEOUT_MS": "<value>", "GOOGLE_SHEETS_MAX_RETRIES": "<value>" } } }}claude_desktop_config.json
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
English | Русский
MCP server for the Google Sheets API: read and write ranges, sheets, formatting, charts, sharing.
A1 Google Sheets MCP lets an AI app work with Google Sheets in plain language. Find a spreadsheet, read its data, write and append rows, shape sheets and formatting, build charts and share the result.
It uses the Google Sheets API with your Google account. It separates reading from writing, keeps destructive operations explicit and makes the limits of the Sheets API clear instead of implying that every spreadsheet task is possible.
127.0.0.1 with PKCE and keeps the tokens itself — no config files, no restart.raw_request cannot reach Drive.spreadsheets covers every Sheets tool; a Drive scope is needed only for spreadsheet search and sharing.Start with a read-only question:
Find the quarterly budget spreadsheet and summarize what each of its sheets contains.
You: Show me the structure of the sales report spreadsheet — its sheets, their sizes and frozen rows.
Assistant: Shows the sheets with their sizes, frozen headers and the objects on them. Nothing changes.
You: Prepare a “March” sheet as a copy of “February” and clear the numbers, keeping the layout.
Assistant: Shows the plan — duplicate the sheet, rename it and clear the data ranges — then asks for confirmation before changing anything.
You: Confirm.
Assistant: Duplicates the sheet and clears the values. Formatting, data validation and frozen rows stay.
You need Node.js 20+ and a Google account. Credentials are not required at install time — the server connects from the conversation.
In the app: open Settings → MCP servers, select Add server, choose STDIO, enter the command npx -y @a1-x-tech/mcp-google-sheets@latest and environment variables GOOGLE_SHEETS_CLIENT_ID, GOOGLE_SHEETS_CLIENT_SECRET, GOOGLE_SHEETS_REFRESH_TOKEN, then select Save and Restart.
From the command line:
codex mcp add google-sheets \
-- npx -y @a1-x-tech/mcp-google-sheets@latest
codex mcp list
claude mcp add \
--transport stdio --scope user google-sheets \
-- npx -y @a1-x-tech/mcp-google-sheets@latest
claude mcp list
The current official path is Settings → Extensions. For a custom desktop extension, open Advanced settings → Extension Developer → Install Extension…, select a .mcpb file and follow the prompts.
This repository currently publishes an npm stdio package and does not contain a .mcpb bundle. For Claude Desktop builds that still support local configuration, use the following JSON stdio configuration as a fallback:
{
"mcpServers": {
"google-sheets": {
"command": "npx",
"args": ["-y", "@a1-x-tech/mcp-google-sheets@latest"]
}
}
}
In those builds, save it to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows.
Add this to ~/.cursor/mcp.json on macOS/Linux or %USERPROFILE%\.cursor\mcp.json on Windows:
{
"mcpServers": {
"google-sheets": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@a1-x-tech/mcp-google-sheets@latest"]
}
}
}
Run MCP: Open User Configuration and add:
{
"servers": {
"google-sheets": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@a1-x-tech/mcp-google-sheets@latest"]
}
}
}
Check it with MCP: List Servers.
'Q3'!A1:F50 and summarize the totals.Sheet1!A1, formulas included.'Sheet name'!A1:C10); structural tools (sheets, formatting, rules, tables, charts) address a numeric sheetId with 0-based indexes. get_spreadsheet supplies the ids — sheet titles are not addresses.append_values adds rows after the last data row; a null cell is skipped, not cleared.clear_values empties values and formulas but keeps formatting, data validation, notes and merges. There is no undo through the API — deleting a sheet, rows or columns destroys their data.batchUpdate is atomic — all of its requests apply or none do.Some spreadsheet features have no dedicated tool: merged cells, named ranges, banding, filters, slicers, find-and-replace and gradient conditional-format rules go through raw_request, which is limited to the Sheets API origin. A new spreadsheet lands in the My Drive root — moving it into a folder is not covered, and manage_permissions cannot transfer ownership.
The AI client controls confirmation prompts. The server marks reads, writes and destructive tools so the client can distinguish an inspection from a live change.
Google Sheets requires OAuth 2.0; an API key is not enough. There are two ways in, and the first one needs no configuration files.
Say "connect Google Sheets" and the assistant runs the flow with you:
setup_instructions prints the checklist: create or select a Google Cloud project, enable Google Sheets API, configure the consent screen and create a Desktop app OAuth client.set_client stores it owner-only. The secret never goes through the conversation.start_login returns a Google consent link. Open it on this machine and approve; the code comes back to a one-shot listener on 127.0.0.1 (PKCE), never through the chat.finish_login exchanges the code and saves the tokens to ~/.config/mcp-google-sheets/credentials.json (mode 0600).The tokens are re-read on every call, so the connection works immediately — no restart of the AI app. auth_status shows what is connected, logout revokes and deletes it.
Create or select a Google Cloud project and enable the Google Sheets API. Also enable the Google Drive API if you want spreadsheet search and sharing.
Configure the OAuth consent screen and create a Desktop app OAuth client.
Authorize the Google account that owns or can edit the spreadsheets. The OAuth 2.0 Playground can obtain the refresh token when Use your own OAuth credentials is enabled.
Request the minimal scope:
https://www.googleapis.com/auth/spreadsheets
It covers every Sheets tool. Only search_spreadsheets and manage_permissions need a Drive scope on top: https://www.googleapis.com/auth/drive, or drive.readonly for search alone, or drive.file for files created through this app.
Testing-mode OAuth refresh tokens can expire after seven days. Publish the OAuth app, or use an Internal app in a Workspace domain, when you need long-lived access. Treat the client secret and refresh token as passwords.
Every variable is optional — with none of them the server connects from the chat.
* Provide either the OAuth trio or an access token. Without credentials the server still starts and lists its tools; the first call names the variables to set.
ASKADS_TELEMETRY=0 to opt out.429, the server uses backoff; reads also retry after network and 5xx errors, while writes are not replayed after an uncertain failure.Found a bug or need a scenario? Create an issue or write in Telegram.
MCP server for the Google Sheets API: read and write ranges, sheets, formatting, charts, sharing.
{ "mcpServers": { "io.github.a1-x-tech-mcp-google-sheets": { "command": "npx", "args": [ "-y", "@a1-x-tech/[email protected]" ], "env": { "GOOGLE_SHEETS_CLIENT_ID": "<value>", "GOOGLE_SHEETS_CLIENT_SECRET": "<secret>", "GOOGLE_SHEETS_REFRESH_TOKEN": "<secret>", "GOOGLE_SHEETS_ACCESS_TOKEN": "<secret>", "GOOGLE_SHEETS_OAUTH_PORT": "<value>", "GOOGLE_SHEETS_API_BASE": "<value>", "GOOGLE_SHEETS_TIMEOUT_MS": "<value>", "GOOGLE_SHEETS_MAX_RETRIES": "<value>" } } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
發布者列出了以下環境變數:GOOGLE_SHEETS_CLIENT_ID, GOOGLE_SHEETS_CLIENT_SECRET, GOOGLE_SHEETS_REFRESH_TOKEN, GOOGLE_SHEETS_ACCESS_TOKEN, GOOGLE_SHEETS_OAUTH_PORT, GOOGLE_SHEETS_API_BASE, GOOGLE_SHEETS_TIMEOUT_MS, GOOGLE_SHEETS_MAX_RETRIES。
Google Sheets MCP 透過 stdio 在本機執行。
上次檢查時間:2026-11-11。 MCP server for the Google Sheets API: read and write ranges, sheets, formatting, charts, sharing.