GoogleSheet MCP

Google Sheets MCP 服务

此 MCP 服务提供了与 Google Sheets 交互的工具，可用于读取、写入和更新电子表格中的数据。

前提条件

• Python 3.8 或更高版本
• Google Cloud Platform 账户
• 要与之交互的 Google Sheet

安装

1. 克隆此仓库：

git clone <your-repository-url>
cd mcp-server-demo

2. 安装所需的软件包：

pip install google-auth-oauthlib google-auth-httplib2 google-api-python-client

3. 下载并放置 credentials.json：
   • 从 Google Cloud Console 下载 credentials.json 文件
   • 将 credentials.json 文件放在与 main.py 相同的目录中
   • 确保文件名正好是 credentials.json

设置 Google Cloud Platform 凭据

1. 前往 Google Cloud Console

2. 创建新项目或选择现有项目

3. 启用 Google Sheets API：

   • 前往“APIs & Services” > “Library”
   • 搜索“Google Sheets API”
   • 点击“Enable”

4. 创建凭据：

   • 前往“APIs & Services” > “Credentials”
   • 点击“Create Credentials” > “Service Account”
   • 填写服务账号详细信息：
     • Name：选择一个描述性名称
     • ID：将自动生成
     • Description：可选的说明
   • 点击“Create and Continue”
   • 对于 Role，选择“Editor”（或根据需要选择适当的角色）
   • 点击“Continue”，然后点击“Done”

5. 创建并下载密钥：

   • 在服务账号列表中，点击刚创建的账号
   • 前往“Keys”标签页
   • 点击“Add Key” > “Create new key”
   • 选择“JSON”格式
   • 点击“Create”
   • JSON 文件将自动下载

6. 保存凭据：

   • 将下载的 JSON 文件重命名为 credentials.json
   • 将其放入 mcp-server-demo 目录

7. 共享 Google Sheet：

   • 打开 Google Sheet
   • 点击“Share”按钮
   • 添加服务账号邮箱（可在 credentials.json 的 client_email 字段中找到）
   • 授予其“Editor”访问权限

运行服务

1. 安装 MCP 服务：

uv run mcp install main.py

2. 服务将启动并准备好接收命令。

添加到 Cursor

要将此 MCP 服务添加到 Cursor，请按以下步骤操作：

1. 打开 Cursor
2. 前往 Cursor -> Preferences -> Cursor Settings -> MCP -> Add new global MCP Server
3. 将以下配置添加到 Cursor 配置文件中：

{
  "mcpServers": {
    "GoogleSheets": {
      "command": "python",
      "args": [
        "main.py"
      ]
    }
  }
}

4. 重启 Cursor 以使更改生效

截图

可用工具

列出电子表格

/tool list_spreadsheets

列出所有与服务账号共享的电子表格。

获取电子表格信息

/tool get_spreadsheet_info "spreadsheet_id"

获取特定电子表格的信息。

获取工作表内容

/tool get_sheet_content "spreadsheet_id"

检索特定工作表的内容。

生成工作表数据

/tool generate_sheet_data "spreadsheet_id"  number_of_records

根据工作表的属性生成逼真的数据。

向工作表添加数据

/tool add_data_to_sheet "spreadsheet_id"  "data_string"

向工作表添加预先生成的数据。

更新工作表记录

/tool update_sheet_record "spreadsheet_id"  "identifier" "updates"

根据 ID 或名称匹配来更新工作表中的记录。

数据格式

添加数据时

数据字符串可以采用以下格式之一：

1. 列表的列表格式：[["value1", "value2"], ["value3", "value4"]]
2. CSV 格式：

value1,value2
value3,value4

更新时

按以下格式提供更改：column1=value1 column2=value2 示例：age=25 [email protected] phone=1234567890

安全注意事项

1. 切勿将 credentials.json 提交到版本控制系统
2. 妥善保管凭据
3. 仅与必要的服务账号共享 Google Sheet
4. 定期轮换凭据

故障排除

常见问题

1. 身份验证错误

   • 确保已将服务账号邮箱添加为电子表格的编辑者
   • 确认 credentials.json 文件有效且未损坏
   • 检查 Google Cloud 项目是否已启用 Google Sheets API

2. 权限错误

   • 确保服务账号拥有正确的权限
   • 确认电子表格已与服务账号邮箱共享
   • 检查电子表格 ID 是否正确

3. 数据格式错误

   • 确保数据格式符合预期结构
   • 检查工作表是否包含所需列（id 或 name）
   • 确认数据中的列数与工作表中的列数一致

支持

如果遇到问题或有疑问，请：

1. 查看日志中的错误消息
2. 按照上述说明检查设置
3. 确保满足所有先决条件
4. 联系 [email protected]