Gdocs MCP

Google表格MCP服务器

一种模型上下文协议（MCP）服务器，提供对Google表格的只读访问。这允许Claude Desktop和其他MCP客户端使用简单的基于URL的工具从您的Google电子表格中读取数据。

快速设置指南

选择您的设置方法:

推荐：个人认证（生产就绪）

• 📗 SETUP_GUIDE.md -个人身份验证设置（~5-10分钟）

- 每个用户都使用自己的Google帐户进行身份验证 - 个人审计跟踪和访问控制 - 最适合：生产使用、合规性、个人责任 - 需求：管理员必须提供凭据文件并将您添加为测试用户

替代方案：共享令牌（快速测试）

• 📘 QUICK_SETUP.md -使用共享令牌进行最快设置（约2分钟）

- 所有用户共享管理员令牌 - 最适合：小团队、原型、仅快速测试 - 权衡：没有单独的审核跟踪，所有更改都以管理员身份显示

详细技术信息，继续阅读下面。

特性

• 只读访问 到您的Google表格
• OAuth 2.0身份验证 用于安全访问
• 三个简单的工具:

- google_sheets_get_info -获取电子表格元数据 - google_sheets_list_tabs -列出所有选项卡/工作表 - google_sheets_get_tab_data -从选项卡读取单元格数据

• 灵活的输出格式 （Markdown和JSON）
• A1符号 支持范围选择

安装

1.安装依赖项

# Clone or download this repository, then:
cd google-sheets-mcp-server
npm install

2.构建服务器

npm run build

这将TypeScript编译为JavaScript dist/ 目录。

谷歌云设置

您需要OAuth 2.0凭据进行身份验证。

团队成员

您的管理员将提供:

1. OAuth凭据文件(google-sheets-mcp-credentials.json)
2. 将您的Google帐户电子邮件添加为GCP中的测试用户
3. 与您的Google帐户共享相关的Google表格

您的设置：关注 SETUP_GUIDE.md

益处:

• 个人用户责任
• 管理员控制谁可以进行身份验证
• 每个用户的操作都会在审核日志中显示其姓名
• 安全且合规

______________________________________________________________________

个人开发者（DIY）

如果你只是为自己设置这个:

1. 首选 谷歌云控制台
2. 创建新项目
3. 启用Google Sheets API
4. 创建OAuth 2.0凭据：

- 首选 API和服务 → 凭证 - 创建 OAuth客户端ID → 桌面应用程序 - 下载JSON文件

1. 配置OAuth同意屏幕（将自己添加为测试用户）
2. 将凭据另存为 ~/.google-sheets-mcp-credentials.json
3. 继续 首次授权

______________________________________________________________________

首次授权

设置凭据后，通过运行以下命令进行身份验证：

node exchange-token.js

发生了什么:

1. 打开浏览器以谷歌登录
2. 使用您的Google帐户登录
3. 点击 允许 授予访问权限
4. 令牌自动保存到 ~/.google-sheets-mcp-token.json

备注：每个用户都使用自己的Google帐户进行身份验证（即使共享凭据文件）。

Claude桌面配置

将此添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "google-sheets": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/google-sheets-mcp-server/dist/index.js"
      ]
    }
  }
}

重要：替换 /ABSOLUTE/PATH/TO/google-sheets-mcp-server 使用安装此服务器的实际绝对路径。

示例路径:

• macOS： /Users/yourname/projects/google-sheets-mcp-server/dist/index.js
• Linux： /home/yourname/projects/google-sheets-mcp-server/dist/index.js
• 窗户： C:\Users\yourname\projects\google-sheets-mcp-server\dist\index.js

小贴士：通过运行获取绝对路径 pwd 在项目目录中：

cd google-sheets-mcp-server
pwd  # Copy this path and append /dist/index.js

重新启动克劳德桌面 更新配置后。

使用示例

在Claude Desktop中配置后，您可以使用自然语言：

获取电子表格信息

"Tell me about this Google Sheet: https://docs.google.com/spreadsheets/d/YOUR_SPREADSHEET_ID/edit"

列出所有选项卡

"What tabs are in this spreadsheet: [URL]"

从选项卡读取数据

"Read all data from the 'Sales' tab in this sheet: [URL]"

"Get cells A1 to D10 from Sheet1 in this spreadsheet: [URL]"

指定输出格式

"Read the Data tab from [URL] and return it as JSON"

工具参考

google_sheets_get_info

获取电子表格的元数据。

参数:

• url （字符串，必填）：谷歌表格URL
• response_format （字符串，可选）： "markdown" 或 "json" （默认值： "markdown")

示例:

{
  "url": "https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit",
  "response_format": "json"
}

google_sheets_list_tabs

列出电子表格中的所有选项卡/工作表。

参数:

• url （字符串，必填）：谷歌表格URL
• response_format （字符串，可选）： "markdown" 或 "json" （默认值： "markdown")

google_sheets_get_tab_data

从特定选项卡读取单元格数据。

参数:

• url （字符串，必填）：谷歌表格URL
• tab_name （string，必填）：选项卡的名称（例如，“Sheet1”）
• range （字符串，可选）：A1表示法范围（例如，“A1:D10”）
• response_format （字符串，可选）： "markdown" 或 "json" （默认值： "markdown")

范围示例:

• "A1:D10" -特定矩形范围
• "B:E" -B列至E列（所有行）
• "A1:Z" -从第1行开始的所有列
• 省略范围以读取整个工作表

发展

以开发模式运行

npm run dev

这使用 tsx watch 用于在开发过程中自动重新加载。

为生产而建

npm run build

清洁构建工件

npm run clean

故障排除

“找不到凭据文件”

原因：OAuth凭据文件缺失

解决方案:

• 团队成员：从管理员处获取凭据文件
• DIY用户：在Google Cloud控制台中创建凭据（请参阅上面的Google Cloud设置）
• 验证文件位置： ls ~/.google-sheets-mcp-credentials.json

“拒绝访问”或“错误403”

原因：未在GCP中添加为测试用户

解决方案:

• 请联系您的管理员，将您的Google帐户电子邮件添加为GCP OAuth同意屏幕中的测试用户
• 确保您使用正确的Google帐户进行身份验证
• 重新运行： node exchange-token.js

“身份验证令牌已过期”

原因：令牌需要刷新

解决方案:

# Delete expired token
rm ~/.google-sheets-mcp-token.json

# Re-authenticate
node exchange-token.js

“无法读取电子表格”或“权限被拒绝”

原因：工作表未与您的Google帐户共享

解决方案:

1. 验证电子表格URL是否正确
2. 确保该表与您的Google帐户电子邮件共享
3. 检查您是否使用正确的Google帐户进行了身份验证
4. 请管理员将该表与您的Google帐户共享

“无效的Google表格URL”

原因：URL格式不正确

所需格式:

https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit

安全说明

个人身份验证模型

• 个人责任：每个用户都使用自己的Google帐户进行身份验证
• 审计跟踪：所有操作都会在Google表格历史记录中显示单个用户的姓名
• 访问控制：管理员控制谁可以进行身份验证以及他们可以访问哪些工作表
• 令牌隔离：每个用户都有自己的令牌；受损令牌只影响一个用户

文件安全性

• 凭据文件 (~/.google-sheets-mcp-credentials.json)：OAuth应用程序配置，可在团队内安全共享
• 令牌文件 (~/.google-sheets-mcp-token.json)：个人身份验证令牌，切勿共享

数据保护

• 本地认证：本地存储在计算机上的OAuth令牌
• 无数据传输：数据仅在Google Sheets API和本地Claude实例之间流动
• 最小范围：仅请求必要的权限（电子表格访问）
• 撤销访问权限：参观https://myaccount.google.com/permissions随时

管理员控制

• 通过GCP测试用户添加/删除用户
• 与个人用户共享/取消共享特定工作表
• 通过谷歌表格版本历史记录监控活动
• 吊销凭据文件以禁用所有访问

许可证

麻省理工学院

贡献

问题和拉取请求欢迎！