MCP-Google-Sheets

这是一个用TypeScript编写的模型上下文协议（MCP）服务器，它允许AI代理通过类型良好的“工具”安全地与Google表格进行交互。该服务器基于Bun和@modelcontextprotocol/sdk构建，并支持OAuth2和服务账户流。

---

🚀 功能

• 认证
  • 服务账户 通过base64编码的CREDENTIALS_CONFIG
  • OAuth2 使用credentials.json + token.json进行用户范围访问
• 工具
  • create 创建一个新的电子表格（如果配置了，会将其移动到你的Drive文件夹中）。
  • listSheets 列出给定电子表格中的所有工作表标签。
  • renameSheet 重命名现有的工作表标签。
  • createSheet 向电子表格添加新的工作表标签。
  • spreadsheetInfo 获取电子表格的元数据（标题、工作表ID、网格属性）。
  • listSpreadsheets 列出配置的Drive文件夹中的所有电子表格（或My Drive）。
  • shareSpreadsheet 与用户共享电子表格（读者/评论者/写作者），并发送通知。
  • sheetData 从工作表和范围内读取单元格值（或整个工作表）。
  • updateCells 将一个二维数组的值写入A1样式的范围。
  • batchUpdate 在单个请求中应用多个范围更新。
  • addRows / addColumns 在指定索引处插入行或列。
  • copySheet 在电子表格之间复制工作表标签（可选重命名）。

---

📋 先决条件

• Bun (v1.0+) 已安装并在你的PATH中
• 一个Google Cloud项目，其中包含：
  • 启用了Sheets API 和 Drive API
  • 一个OAuth2客户端ID（下载credentials.json）或一个服务账户密钥（下载service_account.json）
• （可选）如果你希望新表格移出My Drive，需要一个Drive文件夹ID

---

⚙️ 设置

1. 克隆仓库

   git clone https://github.com/yourusername/mcp-google-sheets.git
   cd mcp-google-sheets
   

2. 安装依赖

   bun install
   

3. 配置环境

   创建一个.env（或导出）：

   # base64编码的服务账户密钥JSON（可选）
   CREDENTIALS_CONFIG=BASE-64 ENCODED SERVICE_ACCOUNT.JSON
   
   
   # 或将你的OAuth2 JSON文件放在index.ts旁边：
   #   credentials.json  (OAuth客户端秘密)
   #   token.json        (首次运行OAuth后生成)
   
   # 用于访问电子表格的Google电子邮件地址
   EMAIL_ID="请输入您将用来访问电子表格的电子邮件地址"
   # （可选）存储新表格的Drive文件夹ID
   DRIVE_FOLDER_ID=1a2B3c4D5e6F...
   

   提示：在Linux/macOS上你可以这样做

   export CREDENTIAL
   S_CONFIG=$(base64 service_account.json | tr -d '\n')
   

▶️ 运行服务器

bun index.ts

在第一次OAuth2运行（如果使用credentials.json）时，你会看到一个URL。访问它，授予访问权限，然后将代码粘贴回终端。token.json将自动生成。

🔧 它是如何工作的

初始化

• initContext()选择你的认证方法（服务账户 → OAuth2 → 错误）。

• 构建google.sheets & google.drive客户端并将它们存储在一个共享上下文中。

MCP工具注册

• 每个“工具”（例如create, listSheets, sheetData）都通过server.tool(...)注册。

传输

• 使用StdioServerTransport，以便Claude可以通过stdin/stdout调用工具。

调用

代理发送一个JSON请求：

{ "tool": "create", "args": { "title": "预算Q2" } }

服务器运行你的处理器，调用Google API，并返回封装在JSON中的结果。

🛠️ 尝试一下

按照上述步骤克隆并配置。

启动服务器：

bun index.ts
通过Claude调用一个工具

示例

❤️ 贡献

欢迎打开问题或PR以添加新工具、修复错误和改进功能。