MCP Gsheet

🚀 MCP 谷歌表格服务器

本项目提供了一个模型上下文协议（MCP）服务器，可实现与谷歌表格的交互。它能够列出电子表格中的工作表，读取特定单元格范围的数据，以及向特定单元格范围写入数据。不过，该项目不提供管理 Google Drive 文件（如列出、创建、删除文件/文件夹）的工具，访问范围仅限于电子表格内容。

✨ 主要特性

• 可列出电子表格中的工作表（标签页）。
• 支持从特定的单元格范围读取数据。
• 能够向特定的单元格范围写入数据。

📦 安装指南

先决条件

1. Python 3.11+
2. 启用 Google Sheets API 的 Google Cloud 项目
3. 服务账户密钥：
   • 前往 Google Cloud Console 创建一个新的服务账户。
   • 下载服务账户密钥文件（JSON 格式）。
   • 向该服务账户授予访问目标电子表格的“编辑器”角色。

安装步骤

1. 克隆仓库

   git clone https://github.com/shionhonda/mcp-gsheet.git
   

2. 设置 Google 凭据
   • 设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量为下载的服务账户密钥文件的绝对路径。

   export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"
   

   • 或者，将密钥文件放置在 Google Cloud 客户端库识别的标准位置（不推荐用于共享环境）。
3. 安装依赖项

   uv venv
   source .venv/bin/activate
   

💻 使用示例

运行服务器

使用 MCP 检查器开发服务器：

mcp dev server.py

运行服务器：

mcp run server.py

服务器将启动并侦听标准输入/输出（stdio）上的 MCP 请求。

Claude Desktop 配置

在你的 Claude Desktop 配置中添加以下内容：

{
  "mcpServers": {
    "gsheet": {
      "command": "/path/to/uv",
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json"
      },
      "args": ["--directory", "/path/to/mcp-gsheet", "run", "server.py"]
    }
  }
}

📚 详细文档

MCP 工具提供的功能

• list_sheets(spreadsheet_id: str) -> list[str]：列出指定电子表格中的所有工作表名称。
• read_cells(spreadsheet_id: str, range_name: str) -> list[list[str]]：从给定的范围（例如 'Sheet1!A1:B5'）读取数据。
• write_cells(spreadsheet_id: str, range_name: str, values: list[list[str]]) -> str：将提供的二维字符串列表写入指定的起始单元格/范围（例如 'Sheet1!C1'）。