AI导哈

Google Sheets集成服务

一个通过FastAPI暴露的REST端点，允许对Google Sheets执行读取、添加、编辑和删除操作，适用于需要自动化表格数据管理的场景。

  • by dieLopes
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 dieLopes/sheets-mcp-server

使用说明

MCP 服务器 - Google Sheets 集成

这个项目通过暴露一个REST端点 FastAPI 这允许在电子表格中执行操作 Google 表格。
访问电子表格是通过一个 服务账户 使用 credentials.json 格式的凭据连接到 Google Cloud。

该服务还公开了一个/mcp.json的终端点，其中包含了终端点的合约（或接口定义）。

💡 什么是 credentials.json？

⁠credentials.json⁠是Google Cloud生成的文件，其中包含您的凭据 服务账户。
它允许服务器无需手动登录即可访问Google的API（Google Sheets和Google Drive），从而确保自动集成。

⚠ 重要提示： 这个文件是敏感的，而且 不应进行版本控制 没有 Git。请将您的名字添加到 .gitignore 中。

🛠 如何生成 credentials.json 文件

1.访问 Google Cloud Console
👉 https://console.cloud.google.com/ 的中文翻译可以是：“https://console.cloud.google.com/（谷歌云控制台）”。不过，通常网址本身不需要翻译，这里的翻译主要是为了说明网址所指向的服务或平台名称。在实际使用中，直接使用网址即可

2.创建或选择一个项目

3.启用所需的API

  • 激活 谷歌表格API
  • 激活 谷歌云端硬盘API

4.创建一个服务账户

  • 前往 IAM 和 Admin > 服务帐号
  • 点击 创建服务账户
  • 定义一个名称（例如：mcp-bot）
  • 完成创建

5.获取JSON密钥

  • 在创建的服务账户中，转到选项卡 “Chaves”在中文中可以翻译为“钥匙”或者根据上下文可能指的是“钥匙孔”（但“chaves”直接翻译为“钥匙孔”并不常见，通常“钥匙孔”会用更具体的描述或术语来表达）。不过，最直接的翻译还是“钥匙”
  • 点击“添加密钥”>“创建新密钥”> 类型 JSON（JavaScript对象表示法）
  • 一个.json文件将会被下载——将其重命名为credentials.json，并放在项目根目录（或其他安全位置）

6.提供电子表格的访问权限

  • 在Google Sheets中打开电子表格
  • 与服务账户的电子邮件共享（在JSON中：“client_email”: “xxxx@project.iam.gserviceaccount.com”）
  • 给予许可 编辑

⚙ `.env` 文件配置

在项目根目录下创建一个 .env 文件：

PLANILHA_NOME=NomeExatoDaSuaPlanilha
GOOGLE_CREDS_PATH=credentials.json

执行项目

uvicorn main:app --reload --port 5000

📡 终端点 /execute

该端点允许读取、添加、编辑或删除电子表格工作表中的数据。

POST /执行 请求体

{
  "acao": "ler",
  "aba": "Aba1",
  "dados": null
}

字段：

操作 → “阅读”、“添加”、“编辑”或“删除” aba → 电子表格中的标签名称 数据 → 结构根据动作而变化： 译文：阅读：无 添加：{ "列1": "值1", "列2": "值2" } 编辑：{ "行": 2, "列": 3, "新值": "文本" } 移除：{ "行": 5 }

示例：

Ler（注：这是一个名字或特定术语，在中文中没有直接对应的翻译，所以保持原样）

curl -X POST http://localhost:5000/executar \
-H "Content-Type: application/json" \
-d '{"acao": "ler", "aba": "Aba1"}'

添加

curl -X POST http://localhost:5000/executar \
-H "Content-Type: application/json" \
-d '{
  "acao": "adicionar",
  "aba": "Aba1",
  "dados": { "ticker": "PETR4", "quantidade": 100, "preco": 37.5 }
}'

编辑

curl -X POST http://localhost:5000/executar \
-H "Content-Type: application/json" \
-d '{
  "acao": "editar",
  "aba": "Aba1",
  "dados": { "linha": 2, "coluna": 3, "novo_valor": "texto atual" }
}'

移除

curl -X POST http://localhost:5000/executar \
-H "Content-Type: application/json" \
-d '{
  "acao": "remover",
  "aba": "Aba1",
  "dados": { "linha": 5 }
}'

📜 标准回复

{
  "status": "ok",
  "mensagem": "Linha adicionada com sucesso",
  "dados": [ ... ] // Apenas na ação de leitura
}

⚠ 安全

永远不要公开credentials.json文件。 调整电子表格的权限设置，以避免未经授权的访问。

📄 MCP宣言

mcp.json 制表文件描述了服务器、其工具和模式。 使用示例：

curl http://localhost:8000/mcp.json

相关 MCP