使用说明

MCP谷歌表格服务器

一个用Go编写的模型上下文协议（MCP）服务器，提供与GoogleSheetsneneneba API的本地集成。此服务器使Claude和其他MCP客户端能够创建、读取、更新和管理Google表格，而无需借助xlsx文件或Python代码。

特性

阅读谷歌表格：通过灵活的范围选择从任何工作表中检索数据
写入和更新：将数据写入特定范围或更新现有内容
附加数据：在不覆盖现有数据的情况下向工作表添加新行
创建电子表格：以编程方式创建新的Google表格
表单管理：添加新工作表（选项卡）、清除数据、获取电子表格元数据
按文件访问控制：明确地将每个电子表格分配为 read 或 readwrite
原生Go实现：快速、轻便、高效
MCP协议：与Claude Code和其他MCP客户端完全兼容

重大变更

v2.0.0版本

batch_update 工具已拆下：通用批处理更新工具已被删除。添加工作表、格式化等操作可以通过专用工具完成(add_sheet, write_sheet等等）。如果你依赖 batch_update 对于格式化或其他低级API操作，您现在将收到 tool not found 错误——这些用例没有直接的迁移路径。
需要每个文件的访问控制：现在必须在中明确列出所有电子表格ID sheets.json 他们的访问级别。服务器不再授予经过身份验证的用户对所有工作表的访问权限。

先决条件

达到1.21或更高
谷歌账户（无需GCP项目！）
OAuth 2.0客户端凭据（易于设置）

快速开始

1.设置OAuth 2.0凭据

首选谷歌云控制台
创建新项目（或使用现有项目）
启用Google Sheets API：
- 导航到“API和服务”>“库”
- 搜索“Google Sheets API”
- 点击“启用”
配置OAuth同意屏幕：
- 转到“API和服务”>“OAuth同意屏幕”
- 选择“外部”用户类型（除非您有谷歌工作区）
- 填写应用程序名称（例如“MCP谷歌表格”）
- 将您的电子邮件添加为开发人员联系人
- 点击“保存并继续”
- 添加范围： https://www.googleapis.com/auth/spreadsheets
- 点击“保存并继续”
- 将您的电子邮件添加为测试用户
- 点击“保存并继续”
创建OAuth 2.0客户端ID:
- 转到“API和服务”>“凭据”
- 点击“创建凭据”>“OAuth客户端ID”
- 选择“桌面应用程序”作为应用程序类型
- 为其命名（例如，“MCP谷歌表格桌面”）
- 点击“创建”
- 下载JSON文件
- 另存为 oauth_credentials.json 在项目目录中

2.安装和构建

# Clone the repository
git clone https://github.com/conallob/mcp-google-sheets.git
cd mcp-google-sheets

# Download dependencies
go mod download

# Build the server
go build -o mcp-google-sheets

# Or run directly
go run main.go

3.首次运行-OAuth身份验证

第一次运行时，系统会提示您授权应用程序：

# Run the server (it will guide you through OAuth)
./mcp-google-sheets

服务器将：

显示授权URL
自动打开浏览器（或复制/粘贴URL）
要求您使用您的Google帐户登录
请求访问您的Google表格的权限
保存访问令牌以备将来使用

授权后，您可以访问您拥有或有权访问的任何Google表格，无需与服务帐户共享！

MCP客户端配置

Claude代码配置

添加到您的Claude Code MCP设置中（通常在 ~/.claude/mcp_settings.json 或通过克劳德代码设置）：

{
  "mcpServers": {
    "google-sheets": {
      "command": "/path/to/mcp-google-sheets/mcp-google-sheets",
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/oauth_credentials.json"
      }
    }
  }
}

备注：如果你不设置 GOOGLE_OAUTH_CREDENTIALS 环境变量，服务器将查找 oauth_credentials.json 在：

当前目录
~/.config/mcp-google-sheets/oauth_credentials.json

您还可以使用单个环境变量：

{
  "mcpServers": {
    "google-sheets": {
      "command": "/path/to/mcp-google-sheets/mcp-google-sheets",
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

其他MCP客户端

对于其他MCP客户端，请使用以下配置服务器：

命令：通往 mcp-google-sheets 二进制
环境（可选）：设置 GOOGLE_OAUTH_CREDENTIALS 到您的OAuth凭据文件路径
协议：stdio（标准输入/输出）

图纸访问控制

服务器仅访问配置文件中明确列出的电子表格。默认情况下，此文件位于 ~/.config/mcp-google-sheets/sheets.json，或者您可以用以下命令覆盖路径 GOOGLE_SHEETS_CONFIG.

{
  "sheets": [
    {
      "id": "1abc123def456ghi789",
      "name": "My Budget",
      "access": "readwrite"
    },
    {
      "id": "2xyz987uvw654rst321",
      "name": "Shared Report",
      "access": "read"
    }
  ]
}

id （必填）：URL中的电子表格ID。
name （可选）：人类可读标签，显示如下 list_sheets.
access: "read" （只读）或 "readwrite" （完全读/写）。

任何针对此处未列出的电子表格的工具调用都会被拒绝，无论经过身份验证的谷歌帐户可以访问什么。

重要提示： 删除a readwrite 入口从 sheets.json 做不撤销缓存的OAuth令牌的写入范围。令牌将保留其授予的权限，直到过期或被明确撤销。要立即删除写访问权限，请删除 ~/.config/mcp-google-sheets/token.json 并重新启动服务器——系统将提示您使用更窄的（只读）范围重新授权。

可用工具

read_sheet

从谷歌表格中读取数据。

参数：

spreadsheet_id （必填）：URL中的电子表格ID
range （可选）：A1符号范围（例如，“Sheet1！A1:D10”）。默认为整个第一页。

例子：

{
  "spreadsheet_id": "1abc123def456",
  "range": "Sheet1!A1:C10"
}

write_sheet

将数据写入谷歌表格，覆盖现有内容。

参数：

spreadsheet_id （必填）：电子表格ID
range （必填）：要写入的A1符号范围
values （必填）：二维值数组（行和列）

例子：

{
  "spreadsheet_id": "1abc123def456",
  "range": "Sheet1!A1:C2",
  "values": [
    ["Name", "Age", "City"],
    ["Alice", "30", "NYC"]
  ]
}

附录_表格

将数据附加到工作表的最后一行数据之后。

参数：

spreadsheet_id （必填）：电子表格ID
range （必填）：指示要附加到哪些列的范围
values （必需）：要附加的二维值数组

例子：

{
  "spreadsheet_id": "1abc123def456",
  "range": "Sheet1!A:C",
  "values": [
    ["Bob", "25", "SF"],
    ["Charlie", "35", "LA"]
  ]
}

create_spreadsheet

创建一个新的谷歌电子表格。

参数：

title （必填）：新电子表格的标题
sheets （可选）：要创建的图纸名称数组

例子：

{
  "title": "My New Spreadsheet",
  "sheets": ["Data", "Analysis", "Summary"]
}

退货： 电子表格ID和URL。

注：创建后，新的电子表格ID不会自动添加到 sheets.json。使用所需的访问级别手动添加它，并在使用其他工具之前重新启动服务器。

权限模型： create_spreadsheet 至少需要一张纸 sheets.json 和 "access": "readwrite"因为 readwrite OAuth作用域授予对以下对象的写入权限全部经过身份验证的帐户中的电子表格（而不仅仅是中列出的那些 sheets.json)，任何 readwrite 该条目有效地允许在用户的Google Drive中的任何位置创建新的电子表格。如果您只需要写入特定的表格并希望阻止创建新的电子表格，请将所有条目设置为 "access": "read".

get_spreadsheet_info

获取电子表格的元数据。

参数：

spreadsheet_id （必填）：电子表格ID

退货： 有关图纸、尺寸、属性等的信息。

add_sheet

将新工作表（选项卡）添加到现有电子表格中。

参数：

spreadsheet_id （必填）：电子表格ID
sheet_name （必填）：新工作表的名称

clear_sheet

清除指定范围内的所有数据。

参数：

spreadsheet_id （必填）：电子表格ID
range （必填）：A1符号范围清除

用法示例

使用克劳德代码

配置后，您可以要求Claude与您的工作表进行交互：

"Read the data from my spreadsheet 1abc123def456 in range Sheet1!A1:E100"

"Create a new spreadsheet called 'Sales Report 2024' with sheets: Q1, Q2, Q3, Q4"

"Append the following data to my sheet 1abc123def456 in the range Sheet1!A:D:
Name,Product,Quantity,Price
John,Widget,5,29.99
Jane,Gadget,3,49.99"

"Clear the range Sheet1!A1:Z1000 in spreadsheet 1abc123def456"

程序化使用

您还可以将此服务器集成到您自己的MCP客户端应用程序中。服务器通过stdio上的JSON-RPC 2.0进行通信。

查找电子表格ID

电子表格ID位于您的Google表格的URL中：

https://docs.google.com/spreadsheets/d/1abc123def456ghi789/edit
                                      ^^^^^^^^^^^^^^^^
                                      This is the ID

故障排除

身份验证错误

如果你得到“无法加载OAuth配置”，请确保：
- oauth_credentials.json 存在于项目目录中，或者
- GOOGLE_OAUTH_CREDENTIALS 环境变量已设置，或
- GOOGLE_OAUTH_CLIENT_ID 和 GOOGLE_OAUTH_CLIENT_SECRET 设置环境变量
检查Google Sheets API是否已在您的Google Cloud项目中启用
验证您的OAuth同意屏幕是否配置正确

权限错误

经过身份验证的用户必须有权访问电子表格
您可以访问您的Google帐户可以访问的任何表格
无需再与服务帐户共享工作表！

重新验证

如果您需要重新进行身份验证（例如，被撤销的访问权限或不同的帐户）：

# Remove the stored token
rm ~/.config/mcp-google-sheets/token.json

# Or if using custom token location
rm /path/to/your/token.json

# Run the server again to re-authenticate
./mcp-google-sheets

连接错误

检查您的网络连接
检查您的网络是否可以访问Google API
确保防火墙/代理设置允许访问googleapis.com

发展

项目结构

mcp-google-sheets/
├── main.go                      # MCP server implementation
├── main_test.go                 # Integration tests
├── config/
│   ├── config.go               # Sheets access-control config
│   └── config_test.go
├── oauth/
│   ├── oauth.go                # OAuth 2.0 flow
│   └── oauth_test.go
├── sheets/
│   ├── client.go               # Google Sheets REST API client
│   └── client_test.go
├── go.mod                      # Go module definition
├── sheets.example.json         # Example sheets config
└── README.md                   # This file

从源头构建

# Install dependencies
go mod download

# Run tests (if available)
go test ./...

# Build
go build -o mcp-google-sheets

# Build for different platforms
GOOS=linux GOARCH=amd64 go build -o mcp-google-sheets-linux
GOOS=darwin GOARCH=amd64 go build -o mcp-google-sheets-mac
GOOS=windows GOARCH=amd64 go build -o mcp-google-sheets.exe

安全考虑

永不承诺 oauth_credentials.json 或 token.json 到版本控制（已在.gitignore中）

安全地存储OAuth凭据并限制文件权限：

chmod 600 oauth_credentials.json
chmod 600 ~/.config/mcp-google-sheets/token.json

OAuth令牌过期并自动刷新
您可以随时从以下地址撤销访问权限 Google帐户权限
对于生产部署，考虑使用环境变量作为OAuth凭据

贡献

欢迎投稿！请随时提交拉取请求。

许可证

看许可证文件以获取详细信息。

资源

支持

对于问题、疑问或贡献，请使用GitHub问题跟踪器。

使用说明

MCP谷歌表格服务器

特性

重大变更

v2.0.0版本

先决条件

快速开始

1.设置OAuth 2.0凭据

2.安装和构建

3.首次运行-OAuth身份验证

MCP客户端配置

Claude代码配置

其他MCP客户端

图纸访问控制

可用工具

read_sheet

write_sheet

附录_表格

create_spreadsheet

get_spreadsheet_info

add_sheet

clear_sheet

用法示例

使用克劳德代码

程序化使用

查找电子表格ID

故障排除

身份验证错误

权限错误

重新验证

连接错误

发展

项目结构

从源头构建

安全考虑

贡献

许可证

资源

支持

相关 MCP

Markdown微信排版发布工具

谷歌表格集成工具

JSON数据查询与操作服务器

JavaScript逆向标准化服务

OBS控制服务器

Kali Linux MCP服务器