MCP Server for Google Spreadsheets

Google Spreadsheets MCP 服务

一个与 Google Spreadsheets 集成的 Model Context Protocol（MCP）服务实现，可让 AI 助手检索和修改电子表格数据。此服务可让 Claude 直接与您的 Google Sheets 数据交互。

演示

功能

此服务提供以下用于处理 Google Spreadsheets 的工具：

• get_sheets：检索 Google Spreadsheet 中所有工作表的信息，包括名称、尺寸和 ID
• get_sheet_values：检索指定工作表中的值，可选择指定范围
• update_cells：更新工作表中指定单元格范围的值
• batch_update_cells：在单次操作中更新不同工作表中的多个范围
• add_sheet：向现有电子表格添加工作表，并自定义其尺寸

前提条件

• Node.js（v18 或更高版本）
• 已启用 Google Sheets API 的 Google Cloud 项目
• Google Cloud 身份验证凭据
• Claude Desktop（用于与 Claude 集成）

安装

1. 克隆此仓库：

   git clone https://github.com/yourusername/mcp-server-spreadsheet.git
   cd mcp-server-spreadsheet
   

2. 安装依赖项：

   pnpm install
   

身份验证设置

此服务使用 Google Cloud 的 Application Default Credentials 进行身份验证，以访问 Google Sheets。

1. 如果尚未安装，请安装 Google Cloud CLI
2. 登录并授权访问 Google Sheets：

   gcloud auth application-default login --scopes=openid,https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets
   

提示

• 确保已启用 Google 项目的 Sheet API。
• 别忘了在 gcloud auth application-default login 中使用 --scopes 选项

构建和运行

1. 构建项目：

   pnpm build
   

2. 运行服务：

   pnpm start
   

服务将启动，并通过标准输入/输出监听 MCP 命令。

与 Claude for Desktop 集成

要将此服务与 Claude for Desktop 配合使用：

1. 确保已安装并运行 Claude for Desktop

2. 将服务添加到 Claude for Desktop 的配置文件（claude_desktop_config.json）中：

   {
     "mcpServers": {
       "spreadsheet": {
         "command": "node",
         "args": ["/absolute/path/to/mcp-server-spreadsheet/build/index.js"],
         "env": {
           "GOOGLE_PROJECT_ID": "your-google-project-id",
           "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/your/credentials.json"
         }
       }
     }
   }
   

3. 重启 Claude for Desktop 以加载服务

使用示例

与 Claude 集成后，您可以使用自然语言处理电子表格。以下是一些提示词示例：

获取电子表格信息

Could you tell me what sheets are in this spreadsheet? https://docs.google.com/spreadsheets/d/YOUR_SPREADSHEET_ID/edit

获取工作表中的数据

Please show me the data from the "Sales" sheet in this spreadsheet: https://docs.google.com/spreadsheets/d/YOUR_SPREADSHEET_ID/edit

更新数据

Update cells A1:B2 in the "Q1 Budget" sheet with these values: 
- Row 1: 1000, 2000
- Row 2: 3000, 4000
The spreadsheet URL is: https://docs.google.com/spreadsheets/d/YOUR_SPREADSHEET_ID/edit

添加新工作表

Please add a new sheet called "Q2 Planning" to this spreadsheet: https://docs.google.com/spreadsheets/d/YOUR_SPREADSHEET_ID/edit

可用工具

get_sheets

检索电子表格中所有工作表的信息。

参数：

• spreadsheetUrl：Google Spreadsheet 的 URL 或 ID

get_sheet_values

检索电子表格中指定工作表的值。

参数：

• spreadsheetUrl：Google Spreadsheet 的 URL 或 ID
• sheetName：要从中检索数据的工作表名称
• range（可选）：采用 A1 表示法的单元格范围（例如，“A1:D5”）

update_cells

更新指定单元格范围的值。

参数：

• spreadsheetUrl：Google Spreadsheet 的 URL 或 ID
• sheetName：要更新的工作表名称
• range：采用 A1 表示法的单元格范围（例如，“A1:B2”）
• values：要写入的二维值数组（每个内部数组代表一行）

batch_update_cells

在单次操作中更新不同工作表中多个范围的值。

参数：

• spreadsheetUrl：Google Spreadsheet 的 URL 或 ID
• updates：更新操作数组，每项包含：
  • sheetName：要更新的工作表名称
  • range：采用 A1 表示法的单元格范围
  • values：要写入的二维值数组

add_sheet

向现有电子表格添加工作表。

参数：

• spreadsheetUrl：Google Spreadsheet 的 URL 或 ID
• sheetTitle：新工作表的标题
• rowCount（可选）：行数（默认值：1000）
• columnCount（可选）：列数（默认值：26）

开发

项目结构

• src/index.ts：主入口点
• src/tools/：各个 MCP 工具的实现
• src/utils/：实用函数和服务
• src/types/：TypeScript 类型定义

运行测试

pnpm test

环境变量

你可以在项目根目录中创建一个 .env 文件，并设置以下变量：

# Optional: Override Google API credentials path
GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json

# Optional: Debug mode
DEBUG=true

故障排查

• 身份验证错误：确保已设置正确的凭据，并在 Google Cloud 项目中启用了 Google Sheets API。
• 权限错误：确保你的 Google 账号或服务账号有权访问你尝试访问的电子表格。
• 服务连接：检查 Claude for Desktop 是否已正确配置为启动 MCP 服务。

许可证

MIT

贡献

欢迎贡献！请随时提交 Pull Request。