Google Sheets 自动化工具

一个基于Python的MCP服务器,作为MCP兼容客户端(如Claude Desktop)与Google Sheets API之间的桥梁,支持自动化数据操作和工作流。

  • by Roelovanheeren
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Roelovanheeren/sheet-mcp

使用说明

mcp-google-sheets

Your AI Assistant's Gateway to Google Sheets! 📊


🤔 这是什么?

mcp-google-sheets 是一个基于Python的MCP服务器,充当任何兼容MCP的客户端(如Claude Desktop)和Google Sheets API之间的桥梁。它允许您使用一组定义好的工具与Google电子表格进行交互,从而实现由AI驱动的强大自动化和数据操作工作流程。

🚀 快速入门(使用 uvx)

从本质上讲,服务器运行在一行中: uvx mcp-google-sheets@latest.

此cmd将自动下载最新代码并运行。 我们建议始终使用 @latest 以确保您拥有具有最新功能和错误修复的最新版本。

  1. ☁️ 先决条件:谷歌云设置

    • 你 必须 首先配置Google Cloud Platform凭据并启用必要的API。我们强烈建议使用 服务账户.
    • ➡️ 跳到 详细的Google云平台设置 下面的指南。
  2. 🐍 安装 uv

    • uvx 是...的一部分 uv,一个快速的Python包安装程序和解析器。如果您还没有安装它:
      # macOS / Linux
      curl -LsSf https://astral.sh/uv/install.sh | sh
      # Windows
      powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
      # Or using pip:
      # pip install uv
      
      按照安装程序输出中的说明添加 uv 如有需要,请前往您的路径。
  3. 🔑 设置基本环境变量(建议使用服务帐户)

    • 您需要告诉服务器如何进行身份验证。在终端中设置这些变量:
    • (Linux/macOS)
      # Replace with YOUR actual path and folder ID from the Google Setup step
      export SERVICE_ACCOUNT_PATH="/path/to/your/service-account-key.json"
      export DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
      
    • (Windows CMD)
      set SERVICE_ACCOUNT_PATH="C:\path\to\your\service-account-key.json"
      set DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
      
    • (Windows PowerShell)
      $env:SERVICE_ACCOUNT_PATH = "C:\path\to\your\service-account-key.json"
      $env:DRIVE_FOLDER_ID = "YOUR_DRIVE_FOLDER_ID"
      
    • ➡️ 看 详细的身份验证和环境变量 对于其他选项(OAuth, CREDENTIALS_CONFIG).
  4. 🏃 运行服务器!

    • uvx 将自动下载并运行最新版本的 mcp-google-sheets:
      uvx mcp-google-sheets@latest
      
    • 服务器将启动并打印日志,表明它已准备就绪。
    • 💡 专业提示: 始终使用 @latest 以确保您获得具有错误修复和功能的最新版本。没有 @latest, uvx 可能会使用缓存的旧版本。

  5. 🔌 连接您的MCP客户端

    • 配置您的客户端(例如Claude Desktop)以连接到正在运行的服务器。
    • 根据您使用的客户端,您可能不需要步骤4,因为客户端可以为您启动服务器。但无论如何,测试运行步骤4以确保设置正确是一种很好的做法。
    • ➡️ 看 使用Claude Desktop 例如。

你准备好了!开始通过MCP客户端发出命令。


✨ 主要特点

  • 无缝集成: 直接连接到Google云端硬盘和Google表格API。
  • 综合工具: 提供广泛的操作(CRUD、列表、批处理、共享、格式化等)。
  • 灵活的身份验证: 支持 **服务帐户(推荐)**OAuth 2.0,以及通过环境变量直接注入凭据。
  • 易于部署: 立即跑步 uvx (零安装感觉)或使用克隆进行开发 uv.
  • AI就绪: 专为与MCP兼容的客户端一起使用而设计,支持自然语言电子表格交互。

🛠️ 可用工具和资源

此服务器公开了以下与Google表格交互的工具:

(除非另有说明,否则输入参数通常为字符串)

  • list_spreadsheets:列出配置的驱动器文件夹(服务帐户)中或用户可访问的电子表格(OAuth)。
    • 退货: 对象列表 [{id: string, title: string}]
  • create_spreadsheet:创建新的电子表格。
    • title (string):所需的标题。
    • 退货: 包含电子表格信息的对象,包括 spreadsheetId.
  • get_sheet_data:从工作表中的某个范围读取数据。
    • spreadsheet_id (字符串)
    • sheet (string):工作表的名称。
    • range (可选字符串):A1表示法(例如。, 'A1:C10', 'Sheet1!B2:D').如果省略,则读取整张表。
    • include_grid_data (可选布尔值,默认为False):如果为True,则包括单元格格式和其他元数据(较大的响应)。如果为False,则仅返回值(更有效)。
    • 退货: 如果 include_grid_data=True,带有元数据的全网格数据。如果 False,一个来自values API的值结果对象。
  • get_sheet_formulas:从工作表中的某个范围读取公式。
    • spreadsheet_id (字符串)
    • sheet (string):工作表的名称。
    • range (可选字符串):A1表示法(例如。, 'A1:C10', 'Sheet1!B2:D').如果省略,则读取整张表。
    • 退货: 二维单元格公式数组。
  • update_cells:将数据写入特定范围。覆盖现有数据。
    • spreadsheet_id (字符串)
    • sheet (字符串)
    • range (字符串):A1表示法。
    • data (2D数组):要写入的值。
    • 退货: 更新结果对象。
  • batch_update_cells:在一个API调用中更新多个范围。
    • spreadsheet_id (字符串)
    • sheet (字符串)
    • ranges (对象):字典将范围字符串(A1表示法)映射到2D值数组 { "A1:B2": [[1, 2], [3, 4]], "D5": [["Hello"]] }.
    • 退货: 批量更新结果对象。
  • add_rows:将行附加到工作表的末尾(在最后一行数据之后)。
    • spreadsheet_id (字符串)
    • sheet (字符串)
    • data (2D数组):要追加的行。
    • 退货: 更新结果对象。
  • list_sheets:列出电子表格中的所有工作表名称。
    • spreadsheet_id (字符串)
    • 退货: 工作表名称字符串列表 ["Sheet1", "Sheet2"].
  • create_sheet:将新工作表(选项卡)添加到电子表格中。
    • spreadsheet_id (字符串)
    • title (string):新工作表的名称。
    • 退货: 新建图纸属性对象。
  • get_multiple_sheet_data:在一次调用中从可能不同的电子表格的多个范围获取数据。
    • queries (对象数组):每个对象都需要 spreadsheet_id, sheet,以及 range. [{spreadsheet_id: 'abc', sheet: 'Sheet1', range: 'A1:B2'}, ...].
    • 退货: 对象列表,每个对象都包含查询参数并已获取 data 或a error.
  • get_multiple_spreadsheet_summary:获取多个电子表格的标题、工作表名称、标题和前几行。
    • spreadsheet_ids (字符串数组)
    • rows_to_fetch (可选整数,默认值5):要预览的行数(包括页眉)。
    • 退货: 每个电子表格的摘要对象列表。
  • share_spreadsheet:与指定的用户/电子邮件和角色共享电子表格。
    • spreadsheet_id (字符串)
    • recipients (对象数组): [{email_address: 'user@example.com', role: 'writer'}, ...].角色: reader, commenter, writer.
    • send_notification (可选布尔值,默认为True):发送电子邮件通知。
    • 退货: 词典与 successes 和 failures 列表。
  • add_columns:向图纸添加列。 (验证参数(如果已实现)
  • copy_sheet:在电子表格中复制工作表。 (验证参数(如果已实现)
  • rename_sheet:重命名现有工作表。 (验证参数(如果已实现)

MCP资源:

  • spreadsheet://{spreadsheet_id}/info:获取有关Google电子表格的基本元数据。
    • 退货: 包含电子表格信息的JSON字符串。

☁️ 谷歌云平台设置(详细)

此设置是 必需的 在运行服务器之前。

  1. 创建/选择GCP项目: 转到 谷歌云控制台.
  2. 启用API: 导航到“API和服务”->“库”。搜索并启用:
    • Google Sheets API
    • Google Drive API
  3. 配置凭据: 你需要做出选择 一 下面的身份验证方法(建议使用服务帐户)。

🔑 身份验证和环境变量(详细)

服务器需要凭据才能访问Google API。选择一种方法:

方法A:服务帐户(建议用于服务器/自动化)✅

  • 为什么? 无头(无需浏览器),安全,非常适合服务器环境。不容易过期。
  • 步骤:
    1. 创建服务帐户: 在GCP控制台->“IAM和管理”->“服务帐户”中。
      • 点击“+创建服务帐户”。命名它(例如。, mcp-sheets-service).
      • 授予角色:添加 Editor 用于广泛访问的角色,或更细粒度的角色(如 roles/drive.file 以及特定的表格角色)以获得更严格的权限。
      • 单击“完成”。找到帐户,单击操作(⋮)->“管理密钥”。
      • 点击“添加密钥”->“创建新密钥”-> JSON ->“创造”。
      • 下载并安全存储 JSON密钥文件。
    2. 创建和共享Google Drive文件夹:
      • 在 Google 云端硬盘,创建一个文件夹(例如“AI管理表”)。
      • 注意 文件夹ID 从URL: https://drive.google.com/drive/folders/THIS_IS_THE_FOLDER_ID.
      • 右键单击文件夹->“共享”->“分享”。
      • 输入服务帐户的电子邮件(来自JSON文件 client_email).
      • 授予 编辑 访问。取消选中“通知人员”。点击“分享”。
    3. 设置环境变量:
      • SERVICE_ACCOUNT_PATH:下载的JSON密钥文件的完整路径。
      • DRIVE_FOLDER_ID:共享Google Drive文件夹的ID。 (参见 超快速启动 对于特定于操作系统的示例)

方法B:Auth2.0(交互式/个人使用)🧑‍💻

  • 为什么? 用于个人使用或本地开发,其中交互式浏览器登录是可以的。
  • 步骤:
    1. 配置OAuth同意屏幕: 在GCP控制台->“API和服务”->“OAuth同意屏幕”中。选择“外部”,填写所需信息,添加范围(.../auth/spreadsheets, .../auth/drive),如果需要,添加测试用户。
    2. 创建OAuth客户端ID: 在GCP控制台->“API和服务”->“凭据”中。“+创建信任”->“OAuth客户端ID”->键入: 桌面应用。命名它。“CREATE”。 下载JSON.
    3. 设置环境变量:
      • CREDENTIALS_PATH:下载的OAuth凭据JSON文件的路径(默认值: credentials.json).
      • TOKEN_PATH:首次登录后存储用户刷新令牌的路径(默认值: token.json).必须可写。

方法C:直接凭证注入(高级)🔒

  • 为什么? 在Docker、Kubernetes或CI/CD等环境中很有用,在这些环境中管理文件很困难,但环境变量很容易/安全。避免文件系统访问。
  • 怎么用? 而不是提供 路径 在凭据文件中,您需要提供 内容 以Base64编码的文件,直接存储在环境变量中。
  • 步骤:
    1. 获取您的凭据JSON文件 (服务帐户密钥或OAuth客户端ID文件)。我们称之为 your_credentials.json.
    2. 生成Base64字符串:
      • (Linux/macOS): base64 -w 0 your_credentials.json
      • (Windows PowerShell):
        $filePath = "C:\path\to\your_credentials.json"; # Use actual path
        $bytes = [System.IO.File]::ReadAllBytes($filePath);
        $base64 = [System.Convert]::ToBase64String($bytes);
        $base64 # Copy this output
        
      • (注意): 避免将敏感凭据粘贴到不受信任的在线编码器中。
    3. 设置环境变量:
      • CREDENTIALS_CONFIG:将此变量设置为 完整的Base64字符串 你刚刚生成。
        # Example (Linux/macOS) - Use the actual string generated
        export CREDENTIALS_CONFIG="ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb..."
        

方法D:应用程序默认凭据(ADC)🌐

  • 为什么? 非常适合谷歌云环境(GKE、计算引擎、云运行)和本地开发 gcloud auth application-default login。不需要显式凭据文件。
  • 怎么用? 使用Google的应用程序默认凭据链自动发现来自多个来源的凭据。
  • ADC搜索顺序:
    1. GOOGLE_APPLICATION_CREDENTIALS 环境变量(服务帐户密钥的路径)- Google的标准变量
    2. gcloud auth application-default login 证书(当地发展)
    3. 从元数据服务器(GKE、Compute Engine等)附加服务帐户
  • 设置:
    • 地方发展:
      1. 跑 gcloud auth application-default login --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/drive 一次
      2. 设置配额项目: gcloud auth application-default set-quota-project <project_id> (替换 <project_id> 使用您的Google Cloud项目ID)
    • 谷歌云: 将服务帐户附加到您的计算资源
    • 环境变量: 集 GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json (谷歌标准)
  • 不需要额外的环境变量 -当其他方法失败时,ADC会自动用作回退。

注: GOOGLE_APPLICATION_CREDENTIALS 是谷歌的官方标准环境变量,而 SERVICE_ACCOUNT_PATH 特定于此MCP服务器。如果你设置 GOOGLE_APPLICATION_CREDENTIALS,ADC会自动找到它。

身份验证优先级和摘要

服务器按以下顺序检查凭据:

  1. CREDENTIALS_CONFIG (Base64内容)
  2. SERVICE_ACCOUNT_PATH (服务帐户JSON路径)
  3. CREDENTIALS_PATH (OAuth JSON路径)-如果令牌丢失/过期,则触发交互流
  4. 应用程序默认凭据(ADC) -自动回退

环境变量摘要:

变量 方法 描述 默认值
SERVICE_ACCOUNT_PATH 服务帐户 服务帐户JSON密钥文件的路径(特定于MCP服务器)。 -
GOOGLE_APPLICATION_CREDENTIALS ADC 服务帐户密钥的路径(谷歌的标准变量)。 -
DRIVE_FOLDER_ID 服务帐户 与服务帐户共享的Google Drive文件夹的ID。 -
CREDENTIALS_PATH OAuth 2.0 OAuth 2.0客户端ID JSON文件的路径。 credentials.json
TOKEN_PATH OAuth 2.0 存储生成的OAuth令牌的路径。 token.json
CREDENTIALS_CONFIG 服务帐户/Outh2.0 Base64编码的JSON凭据字符串内容。 -

⚙️ 运行服务器(详细)

方法1:使用 uvx (推荐给用户)

如图所示 超快速启动,这是最简单的方法。设置环境变量,然后运行:

uvx mcp-google-sheets@latest

uvx 处理临时获取和运行包。

方法2:用于开发(克隆Repo)

如果你想修改代码:

  1. 克隆: git clone https://github.com/yourusername/mcp-google-sheets.git && cd mcp-google-sheets (使用实际URL)
  2. 设置环境变量: 如上所述。
  3. 使用运行 uv: (使用当地代码)
    uv run mcp-google-sheets
    # Or via the script name if defined in pyproject.toml, e.g.:
    # uv run start
    

🟦 节点MCP服务器(Express+MCP SDK)

更喜欢轻量级的JavaScript堆栈?该仓库现在附带了Node/Express MCP服务器(server.js)电源由 @modelcontextprotocol/sdk.

本地设置

  1. 安装deps一次: npm install
  2. 设置以下环境变量(本地或MCP客户端配置中):
    • GCP_SERVICE_ACCOUNT_EMAIL
    • GCP_PROJECT_ID
    • DRIVE_FOLDER_ID
    • 可选但推荐: GOOGLE_APPLICATION_CREDENTIALS 指向用于本地运行的服务帐户JSON文件。在托管环境(Railway、Cloud Run等)中,ADC将自动使用附加的服务帐户。
  3. 启动服务器: npm start
  4. 终点:
    • 流式HTTP: POST /mcp
    • 传统SSE(克劳德桌面/光标兼容性): GET /sse 和 POST /messages?sessionId=...

工具包括:

工具 说明
list_spreadsheets 在中列出电子表格 DRIVE_FOLDER_ID
create_spreadsheet 创建工作表并将其移动到共享文件夹中
append_rows 将行附加到一个范围 USER_ENTERED 语义学

铁路部署(V1)

使用提供的Dockerfile+ .env.example 为了实现清洁的铁路部署:

  1. 共享Drive文件夹 随着 railway-sheets@savvy-depot-472312-k6.iam.gserviceaccount.com (编辑器访问权限)。这是您将其密钥加载到Railway的服务帐户。
  2. 创建服务帐户JSON密钥 对于该身份,Base64对其进行编码,并设置 CREDENTIALS_CONFIG 铁路单线Base64字符串→ 变量。
  3. 设置铁路变量 (也反映在 .env.example):
    • DRIVE_FOLDER_ID=1Wm3RE4MEWWL4kPFhljQgARPQdxT7l0xx
    • PORT=8080
    • LOG_LEVEL=info
    • CREDENTIALS_CONFIG=<base64 service-account json>
    • GCP_PROJECT_ID=savvy-depot-472312-k6
  4. 重新部署。Railway构建了Dockerfile(现在基于 ghcr.io/modelcontextprotocol/python-mcp)并在以下位置启动SSE端点 https://<service>.up.railway.app/sse日志应显示“身份验证方法:服务帐户(从CREDENTIALS_CONFIG解码)”。

提示:如果您不想公开Base64字符串,请将JSON作为Railway文件上传到 /opt/sa.json 并设置 GOOGLE_APPLICATION_CREDENTIALS=/opt/sa.json 相反;该守则尊重这两者。


🚢 部署到Google Cloud Run(无密钥,带工作负载身份联合)

当您想要一个托管的HTTPS/SSE端点(例如,用于AgentKit)而不存储JSON密钥时,请使用此路径。回购现在包括 Dockerfile 加 .github/workflows/deploy-cloud-run.yml 一旦谷歌云+GitHub管道到位,就会自动完成这一过程。

0.你最终会得到什么

  • 云运行URL,如 https://google-sheets-mcp-xxxxxx-uc.a.run.app/sse.
  • 该服务完全作为具有驱动器/表格角色的Google服务帐户运行,但 不 导出密钥。
  • GitHub Actions通过工作负载身份联合会(OIDC)部署每次推送,因此您的仓库永远不会存储长期机密。

1.一次性谷歌云设置

PROJECT_ID=your-project-id
SA_NAME=google-sheets-mcp
SA_EMAIL="$SA_NAME@$PROJECT_ID.iam.gserviceaccount.com"
POOL_ID=gh-pool
PROVIDER_ID=github

gcloud services enable run.googleapis.com \
  cloudbuild.googleapis.com \
  iam.googleapis.com \
  iamcredentials.googleapis.com \
  drive.googleapis.com \
  sheets.googleapis.com

gcloud iam service-accounts create $SA_NAME \
  --display-name="Google Sheets MCP"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SA_EMAIL" \
  --role="roles/drive.file"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SA_EMAIL" \
  --role="roles/sheets.editor"

# Optional but handy for future tuning
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SA_EMAIL" \
  --role="roles/run.admin"
  1. 创建/共享Drive文件夹(例如“AI管理表”),从URL复制文件夹ID,并与共享 google-sheets-mcp@${PROJECT_ID}.iam.gserviceaccount.com 作为 编辑。服务器将仅在此文件夹中列出/创建电子表格。
  2. 创建工作负载标识池+GitHub提供程序(用您的值替换上限):
    PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
    
    gcloud iam workload-identity-pools create $POOL_ID \
      --location="global" \
      --display-name="GitHub OIDC Pool"
    
    gcloud iam workload-identity-pools providers create-oidc $PROVIDER_ID \
      --location="global" \
      --workload-identity-pool=$POOL_ID \
      --display-name="GitHub Provider" \
      --issuer-uri="https://token.actions.githubusercontent.com" \
      --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository,attribute.ref=assertion.ref"
    
  3. 允许您的GitHub仓库模拟服务帐户(锁定到 main 如果需要):
    REPO="OWNER/REPO"
    
    gcloud iam service-accounts add-iam-policy-binding $SA_EMAIL \
      --role="roles/iam.workloadIdentityUser" \
      --member="principalSet://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/attribute.repository/$REPO"
    
    要限制到分支,请附加 /attribute.ref/refs/heads/main (或您的分支)到成员路径,并保持工作流触发器对齐。

2.配置GitHub操作

设置这些 存储库变量 (设置→ 秘密和变量→ 行动→ 变量),因此工作流具有所需的一切:

变量 示例 目的
GCP_PROJECT_ID agent-lab-123456 云构建/运行项目
CLOUD_RUN_REGION us-central1 部署区域
CLOUD_RUN_SERVICE google-sheets-mcp 云运行服务名称
MCP_SERVICE_ACCOUNT google-sheets-mcp@agent-lab-123456.iam.gserviceaccount.com 运行时标识
WORKLOAD_IDENTITY_PROVIDER projects/1234567890/locations/global/workloadIdentityPools/gh-pool/providers/github 完整的提供者资源路径
DRIVE_FOLDER_ID 1AbCdEf123... 与服务帐户共享的文件夹

现在,每次向配置的分支推送都将:

  1. 使用以下内容构建容器 gcloud builds submit 使用提供的 Dockerfile (运行 mcp-google-sheets --transport sse --host 0.0.0.0 --port 8080).
  2. 通过部署到Cloud Run .github/workflows/deploy-cloud-run.yml,附加您的服务帐户并注入 DRIVE_FOLDER_ID.
  3. 在工作流日志中输出服务URL。

3.获取SSE URL并添加到AgentKit

gcloud run services describe $CLOUD_RUN_SERVICE \
  --region $CLOUD_RUN_REGION \
  --format="value(status.url)"

追加 /sse 对于FastMCP SSE客户端:

https://google-sheets-mcp-xxxxxx-uc.a.run.app/sse

将该URL粘贴到AgentKit(工具→ MCP服务器→ “添加服务器”),Auth=None,除非您添加自己的身份验证代理。

4.强化观念

  • 尽量减少驱动器/纸张的角色(roles/drive.file + roles/sheets.editor 限制对共享文件夹的访问)。
  • 移除 --allow-unauthenticated 使用IAP或签名JWT的前Cloud Run会检查您是否需要私有端点。
  • 如果您希望更严格的隔离,请为每个环境使用单独的文件夹/服务帐户。

🔌 使用Claude Desktop

将服务器配置添加到 claude_desktop_config.json 在...之下 mcpServers。选择与您的设置匹配的块:

⚠️ 重要提示:

  • 🍎 macOS用户: 使用完整路径: "/Users/yourusername/.local/bin/uvx" 而不是仅仅 "uvx"
🔵 Config: uvx + Service Account (Recommended)
{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

🍎 macOS注意事项: 如果你得到一个 spawn uvx ENOENT 错误,请使用完整路径 uvx:

{
  "mcpServers": {
    "google-sheets": {
      "command": "/Users/yourusername/.local/bin/uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

替换 yourusername 使用您的实际用户名。

🔵 Config: uvx + OAuth 2.0
{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "CREDENTIALS_PATH": "/full/path/to/your/credentials.json",
        "TOKEN_PATH": "/full/path/to/your/token.json"
      }
    }
  }
}

注意:首次使用时,浏览器可能会打开进行谷歌登录。确保TOKEN_PATH可写。

🍎 macOS注意事项: 如果你得到一个 spawn uvx ENOENT 错误,替换 "command": "uvx" 随着 "command": "/Users/yourusername/.local/bin/uvx" (替换 yourusername 使用您的实际用户名)。

🔵 Config: uvx + CREDENTIALS_CONFIG (Service Account Example)
{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "CREDENTIALS_CONFIG": "ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAi...",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

注意:粘贴CREDENTIALS_CONFIG的完整Base64字符串。服务帐户文件夹上下文仍然需要DRIVE_FOLDER_ID。

🍎 macOS注意事项: 如果你得到一个 spawn uvx ENOENT 错误,替换 "command": "uvx" 随着 "command": "/Users/yourusername/.local/bin/uvx" (替换 yourusername 使用您的实际用户名)。

🔵 Config: uvx + Application Default Credentials (ADC)

选项1:使用GOOGLE_APPLICATION_CREDENTIALS

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
      }
    }
  }
}

选项2:使用gcloud身份验证(不需要env变量)

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {}
    }
  }
}

先决条件:

  1. 跑 gcloud auth application-default login --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/drive 第一。
  2. 设置配额项目: gcloud auth application-default set-quota-project <project_id>

🍎 macOS注意事项: 如果你得到一个 spawn uvx ENOENT 错误,替换 "command": "uvx" 随着 "command": "/Users/yourusername/.local/bin/uvx" (替换 yourusername 使用您的实际用户名)。

🟡 Config: Development (Running from cloned repo)
{
  "mcpServers": {
    "mcp-google-sheets-local": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/mcp-google-sheets",
        "mcp-google-sheets"
      ],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/path/to/your/mcp-google-sheets/service_account.json",
        "DRIVE_FOLDER_ID": "your_drive_folder_id_here"
      }
    }
  }
}

注:使用 --directory 标记以指定项目路径,并调整路径以匹配您的实际工作区位置。


💬 克劳德提示示例

连接后,尝试以下提示:

  • “列出我有权访问的所有电子表格。”(或“在我的AI管理表格文件夹中”)
  • “创建一个名为‘2024年第三季度季度销售报告’的新电子表格。”
  • 在“季度销售报告”电子表格中,获取Sheet1范围A1到E10的数据
  • 将名为“摘要”的新工作表添加到具有ID的电子表格中 1aBcDeFgHiJkLmNoPqRsTuVwXyZ."
  • 在我的“项目任务”电子表格的“任务”表中,将单元格B2更新为“进行中”
  • 将这些行附加到电子表格中的“日志”表中 XYZ: [['2024-07-31', 'Task A Completed'], ['2024-08-01', 'Task B Started']]"
  • “获取电子表格“销售数据”和“库存盘点”的摘要。”
  • “与共享“团队度假时间表”电子表格 team@example.com 作为读者和 manager@example.com 作为一名作家。不要发送通知。"

🤝 贡献

欢迎投稿!请打开一个问题来讨论bug或功能请求。拉取请求受到赞赏。


📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。


🙏 鸣谢