1. 项目概述与核心价值

最近在折腾AI智能体（Agent）的自动化工作流，发现一个挺普遍的需求：如何让AI助手，比如Claude、GPTs，或者基于LangChain搭建的本地Agent，能够安全、可控地访问和操作我的Google Workspace数据？无论是读取Gmail里的重要邮件、在Google Drive里查找文档，还是在Google Calendar上安排日程，手动复制粘贴信息不仅效率低下，还容易出错。市面上虽然有一些现成的API集成方案，但要么权限管理过于宽泛（直接给AI一个OAuth密钥，相当于把家钥匙交给了陌生人），要么配置复杂得让人望而却步。

正是在这个背景下，我注意到了 abcreativ/google-suite-mcp 这个开源项目。MCP，全称是 Model Context Protocol，你可以把它理解为一个标准化的“翻译官”或“适配器”。它的核心使命，是为各种AI模型提供一个统一、安全的方式来调用外部工具和资源。而这个项目，就是专门为MCP协议实现的一个Google Workspace服务端。简单来说，它把你的Google账号（Gmail, Drive, Calendar, Docs等）的能力，封装成一系列标准的“工具”，暴露给支持MCP协议的AI客户端。AI只需要说“帮我查一下昨天客户发的邮件”，MCP服务器就会安全地处理好认证、调用Gmail API、并返回结构化的结果。

这个项目的价值，远不止是“又一个API包装器”。它解决的是AI应用落地的“最后一公里”问题——可信的数据接入。对于开发者而言，它意味着你可以快速构建一个具备Google全家桶能力的AI助手，而无需从零开始研究OAuth 2.0流程、各个Google API的SDK以及复杂的权限管控。对于普通用户，如果配合一个友好的前端（比如一个聊天界面），你就能拥有一个真正理解你工作上下文、并能替你执行任务的数字助理。我花了一周时间，从部署、配置到实际测试，把这个项目摸了个透，过程中踩了不少坑，也总结出了一套稳定可用的实践方案，接下来就和大家详细拆解。

2. 核心架构与MCP协议解析

2.1 什么是MCP，以及为什么需要它？

在深入项目之前，我们必须先理解MCP协议扮演的角色。你可以把AI模型（如Claude 3, GPT-4）想象成一个极其聪明但“与世隔绝”的大脑。它知识渊博，擅长推理和生成文本，但它没有“手”和“眼睛”——它无法直接访问互联网、你的邮箱、你的数据库。传统的方法是，我们在开发AI应用时，会为每一个需要的外部能力（如搜索、发邮件、查数据库）编写一个特定的“函数调用”，然后通过复杂的提示工程（Prompt Engineering）告诉AI：“当你需要查天气时，请调用 get_weather(location) 这个函数。”

这种方式存在几个明显痛点：

  1. 紧耦合 ：AI模型和工具代码深度绑定，更换模型或工具成本很高。
  2. 描述冗余 ：每个工具的功能、参数都需要在系统提示词里详细描述，占用大量Token。
  3. 发现性差 ：AI无法动态知道当前有哪些工具可用，工具列表是静态配置的。
  4. 标准化缺失 ：不同工具返回的数据格式千奇百怪，AI需要额外学习如何解析。

MCP协议就是为了解决这些问题而生的。它定义了一套标准化的通信方式，包括：

  • 工具（Tools）声明 ：服务器（如 google-suite-mcp ）告诉客户端（如AI应用）“我这里有哪些工具可用”，以及每个工具的详细描述、参数格式（基于JSON Schema）。
  • 资源（Resources）声明 ：服务器可以声明一些可读的“资源”（如一个文档的URI），客户端可以按需读取。
  • 调用（Invocation） ：客户端以标准格式请求调用某个工具，并传入参数。
  • 结果（Result） ：服务器执行后，返回结构化的结果（文本、图片、数据等）。

这样一来，AI客户端只需要实现一次MCP协议，就能接入所有遵循该协议的服务器，获得海量的工具能力。 abcreativ/google-suite-mcp 就是这样一个服务器，它把Google Workspace的API“翻译”成了MCP协议的标准工具。

2.2 google-suite-mcp 的架构设计

这个项目采用Node.js编写，架构清晰，核心目录结构如下：

google-suite-mcp/
├── src/
│   ├── servers/          # 核心服务器实现
│   │   ├── google-suite.mjs  # 主服务器文件，工具注册中心
│   │   └── ... (其他可能的功能模块)
│   ├── tools/           # 具体的工具实现
│   │   ├── gmail/       # Gmail相关工具
│   │   ├── drive/       # Drive相关工具
│   │   ├── calendar/    # Calendar相关工具
│   │   └── docs/        # Docs相关工具
│   └── auth/            # 认证相关逻辑
├── .env.example         # 环境变量模板
├── package.json
└── README.md

它的工作流程可以概括为：

  1. 启动 ：加载环境变量，初始化Google API客户端（使用官方 googleapis 库）。
  2. 注册 ：在 google-suite.mjs 中，导入所有工具模块，并将它们注册到MCP服务器实例。
  3. 声明 ：当MCP客户端连接时，服务器会发送一个列表，声明所有可用的工具（例如 gmail_search_messages , drive_list_files , calendar_create_event ）。
  4. 服务 ：客户端发起工具调用请求，服务器找到对应的工具函数，使用认证后的Google API客户端执行操作，并将结果格式化为MCP标准响应。

这种模块化设计的好处是扩展性极强。如果你想增加一个操作Google Sheets的工具，只需要在 tools/sheets/ 下新建一个模块，实现具体的函数，然后在主服务器文件中注册即可，其他部分完全不用动。

注意 ：项目默认使用服务账号（Service Account）进行认证，这适用于服务器端应用。如果你需要代表不同的用户（多租户场景），则需要实现OAuth 2.0授权码流程，这比服务账号复杂得多，需要处理令牌刷新和存储。项目README可能提及，但深度集成需要自己动手。

3. 环境准备与部署实操

3.1 前期准备：Google Cloud项目与服务账号

这是整个流程中最关键、也最容易出错的一步。很多人在配置Google API权限时栽了跟头。

第一步：创建Google Cloud项目

  1. 访问 Google Cloud Console 。
  2. 点击顶部项目下拉菜单，选择“新建项目”。给它起个名字，比如 ai-google-assistant 。
  3. 创建完成后，确保你位于这个新项目中。

第二步：启用所需API 在左侧菜单找到“API和服务” -> “库”。搜索并启用以下API：

  • Gmail API
  • Google Drive API
  • Google Calendar API
  • Google Docs API （如果你需要）
  • 特别注意 ：确保也启用了 Google Workspace Marketplace SDK ，某些域范围内的授权可能需要它。

第三步：创建服务账号并下载密钥

  1. 进入“API和服务” -> “凭据”。
  2. 点击“创建凭据”，选择“服务账号”。
  3. 输入服务账号名称（如 mcp-server-sa ），服务账号ID会自动生成。描述可以写“用于MCP服务器访问Google Workspace”。
  4. 点击“创建并继续”。在“授予此服务账号对项目的访问权限”步骤，暂时不需要添加角色，直接点击“继续”，然后“完成”。
  5. 在服务账号列表中，找到刚创建的服务账号，点击其邮箱进入详情页。
  6. 切换到“密钥”标签页，点击“添加密钥” -> “创建新密钥”。
  7. 密钥类型选择 JSON ，然后点击“创建”。浏览器会自动下载一个JSON文件（如 mcp-server-sa-xxxxxxx.json ）， 请务必妥善保管此文件，它相当于最高权限的密码 。

第四步：为服务账号授予域范围权限（关键步骤！） 服务账号本身只是一个身份，它还没有权限访问任何用户的Google数据。我们需要进行“域范围授权”。

  1. 记录下服务账号详情页中的“唯一ID”（也叫“客户端ID”），格式类似一串数字。
  2. 如果你是Google Workspace的管理员，可以进入管理控制台（admin.google.com）。
  3. 依次进入“安全” -> “访问权限和数据控制” -> “API控制”。
  4. 点击“管理域范围授权”。
  5. 点击“添加新的”。
    • 客户端ID：填入刚才记录的服务账号唯一ID。
    • OAuth范围：这里需要填入你希望授予的权限范围。 这是精细控制权限的关键 。建议至少包括： 
      https://www.googleapis.com/auth/gmail.readonly,
https://www.googleapis.com/auth/drive.readonly,
https://www.googleapis.com/auth/calendar.events
      • readonly 表示只读，更安全。如果你需要AI帮你发送邮件或创建文档，则需要去掉 .readonly ，但这会扩大风险。
    • 应用名称：可以填写 Google Suite MCP Server 。
  6. 点击“授权”。这个操作是告诉Google：“我允许这个服务账号，在它提出请求时，代表域内的用户（或自己）访问指定范围的数据。”

第五步：在目标Google账号中“委派”权限（另一个关键！） 域范围授权是管理员做的全局设置。但具体到“代表哪个用户”，还需要在该用户的账号层面进行“委派”。

  1. 登录你希望AI助手操作的那个具体的Google账号（比如你的个人账号 your.name@gmail.com ）。
  2. 访问这个链接（直接修改URL中的邮箱）： https://admin.google.com/ac/owl/domainwidedelegation?hl=en&authuser=your.name@gmail.com
    • 注意： authuser 参数要换成你的邮箱。这个页面有时对普通用户隐藏，如果无法访问，你可能需要暂时以管理员身份操作，或者通过Google Workspace管理控制台的“安全”-“API控制”找到相关设置。
  3. 在“添加新的客户端访问”部分：
    • 客户端ID：再次填入服务账号的唯一ID。
    • OAuth范围： 精确地、一个不差地 填入你在上一步管理员界面授权的所有范围，用英文逗号分隔。
  4. 点击“授权”。

至此，服务账号才真正获得了代表你的特定用户访问Google数据的权力。这两步授权缺一不可，且范围必须完全匹配，否则会出现 403 权限错误。

3.2 项目部署与配置

假设你已经将 abcreativ/google-suite-mcp 项目克隆到本地。

git clone https://github.com/abcreativ/google-suite-mcp.git
cd google-suite-mcp
npm install

配置环境变量：

  1. 将下载的JSON密钥文件放到项目根目录下，或者一个安全的目录。
  2. 复制 .env.example 文件为 .env 。
  3. 编辑 .env 文件，填入关键信息：
# 你的服务账号JSON密钥文件的**绝对路径**或相对于项目根目录的路径
GOOGLE_APPLICATION_CREDENTIALS="./path/to/your/mcp-server-sa-xxxxxxx.json"

# 你希望代表操作的那个Google账号的邮箱地址
TARGET_USER_EMAIL="your.name@gmail.com"

# MCP服务器监听的端口，默认可能是3000，按需修改
PORT=3000

一个我踩过的巨坑：路径问题 在Docker容器或某些生产环境部署时， GOOGLE_APPLICATION_CREDENTIALS 这个环境变量有时会被其他库（如Google Cloud默认的ADC - Application Default Credentials）优先读取。为了绝对可靠，我建议在代码中显式指定。不过， google-suite-mcp 项目通常会在初始化 googleapis 客户端时，从我们配置的环境变量或默认位置读取。最稳妥的方式是，确保你的密钥文件路径正确，并且运行服务器的用户有读取该文件的权限。

运行服务器： 

npm start
# 或者，如果package.json里定义的是其他脚本，如
# node src/servers/google-suite.mjs

如果一切正常，你应该会在终端看到服务器启动的日志，表明MCP服务器正在指定端口上等待连接。

4. 工具详解与实战调用

服务器跑起来了，我们来看看它具体提供了哪些“武器”。根据源码，核心工具通常包括以下几类：

4.1 Gmail工具集

这是使用频率最高的部分。工具设计得非常贴近自然语言。

  • gmail_search_messages : 搜索邮件。参数可以包括 query （Gmail搜索语法，如 from:example@domain.com after:2024/01/01 ）、 maxResults 。
  • gmail_get_message : 获取特定邮件ID的完整内容，包括正文、附件信息。
  • gmail_send_message : 发送邮件。需要提供 to , subject , body 等。
  • gmail_create_draft : 创建草稿。

实战示例：让AI帮你汇总未读邮件 假设你连接了一个Claude Desktop并配置它使用本地的MCP服务器。你可以这样提示：

“请查看我过去24小时内所有未读的、来自GitHub的通知邮件，把每个邮件的标题和发件人列出来给我。”

AI（Claude）在后台的思考和执行流程会是：

  1. 向MCP服务器查询可用工具，发现 gmail_search_messages 。
  2. 根据你的指令，构造调用参数： {“query”: “is:unread from:notifications@github.com after:2024/10/27”, “maxResults”: 20} 。
  3. 发送调用请求。
  4. MCP服务器收到请求，使用服务账号凭据和 TARGET_USER_EMAIL ，调用Gmail API执行搜索。
  5. API返回邮件列表。MCP服务器将其格式化为清晰的文本（可能是一个Markdown表格），返回给Claude。
  6. Claude将这个结果整合到回复中，呈现给你。

注意事项：

  • 搜索语法 ：充分利用Gmail的搜索操作符（如 is:unread , label:important , has:attachment ），能让AI的查询更精准。
  • 速率限制 ：Google API有配额限制。如果让AI频繁、自动化地查询，可能会触发限制。在工具实现中考虑加入简单的节流或缓存是很好的实践。
  • 内容安全 ：AI将能看到邮件内容。确保你信任所使用的AI客户端，并且通信通道是加密的（如本地运行或HTTPS）。

4.2 Google Drive工具集

用于管理云端文件。

  • drive_list_files : 列出文件。支持按文件夹ID（ folderId ）、文件名搜索（ q 参数，使用Drive查询语法）、排序等。
  • drive_get_file : 获取文件元数据或下载内容（对于文本文档，可直接读取；对于二进制文件，可能需要返回下载链接或Base64）。
  • drive_search_files : 更强大的搜索工具。
  • drive_create_file : 创建文件或文件夹。

实战示例：查找并总结最近的报告

“在我的Google Drive的‘项目报告’文件夹里，找到最近一个月修改过的所有PDF文档，并告诉我它们文件名和最后修改日期。”

AI会调用 drive_list_files ，参数可能为 {“q”: “‘FOLDER_ID’ in parents and mimeType=‘application/pdf’ and modifiedTime > ‘2024-09-28T00:00:00’”, “orderBy”: ‘modifiedTime desc’} 。这里 FOLDER_ID 需要你先通过一次查询获取，或者AI可以通过多次交互来定位。

4.3 Google Calendar工具集

管理日程。

  • calendar_list_events : 列出特定时间范围内的事件。
  • calendar_get_event : 获取事件详情。
  • calendar_create_event : 创建新事件。需要提供 summary , start , end , attendees 等。
  • calendar_update_event / calendar_delete_event : 更新或删除事件。

实战示例：智能安排会议

“下周二下午2点到4点，帮我创建一个名为‘项目同步会’的线上会议，邀请团队成员张三（zhangsan@company.com）和李四（lisi@company.com），并把会议链接发给我。”

AI需要解析时间（“下周二下午2点到4点”），调用 calendar_create_event ，并可能从返回结果中提取 hangoutLink 或 conferenceData 给你。

4.4 工具调用模式与最佳实践

在实际使用中，AI客户端（如Claude）和MCP服务器的交互是自动的，但作为开发者或高级用户，理解其模式有助于调试和设计更好的提示。

  1. 声明式交互 ：你不需要记忆具体的工具名和参数。你只需用自然语言描述任务，AI会自己匹配工具、构造参数。这降低了使用门槛。
  2. 链式调用 ：复杂任务可能涉及多个工具。例如，“把昨天客户邮件里提到的需求文档找出来发给我”。AI可能需要先调用 gmail_search_messages 找到邮件，提取文档名，再调用 drive_search_files 找到文档，最后可能调用 gmail_send_message 或准备一个下载链接。MCP协议支持这种链式调用。
  3. 权限最小化 ：在配置服务账号的OAuth范围时，务必遵循最小权限原则。如果AI只需要读邮件，就不要授予 gmail.modify 或 gmail.compose 权限。这能最大程度降低风险。

5. 安全考量与高级配置

将Google账号的访问权限开放给AI，安全是头等大事。 google-suite-mcp 项目本身是一个服务器，它的安全性取决于你如何部署和使用它。

5.1 核心安全原则

  1. 网络隔离 ：绝对不要将MCP服务器直接暴露在公网（0.0.0.0）。它应该只监听本地回环地址（127.0.0.1）或在内网安全环境中运行。你的AI客户端（如Claude Desktop）和MCP服务器应在同一台机器或受信任的同一内网中。
  2. 认证与传输安全 ：MCP协议本身可以运行在Stdio（标准输入输出）或SSE（Server-Sent Events） over HTTP上。如果使用HTTP，务必使用HTTPS（TLS加密），防止通信被窃听。项目本身可能不包含HTTPS配置，你需要通过反向代理（如Nginx）或Node.js的 https 模块来实现。
  3. 服务账号密钥保护 ：JSON密钥文件是最高机密。不要将其提交到Git仓库。在生产环境中，使用安全的密钥管理服务（如云厂商的KMS、HashiCorp Vault）或环境变量注入，而不是放在文件系统上。
  4. 审计日志 ：在MCP服务器端增加日志记录，记录每一个工具调用的时间、工具名、调用者（客户端标识）和概要（注意不要记录敏感参数如邮件内容）。这有助于事后审计和异常排查。

5.2 使用Docker容器化部署

为了环境一致性和安全性，强烈建议使用Docker部署。

# Dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
# 密钥文件通过Docker Secrets或环境变量注入，不直接COPY
CMD [“node”, “src/servers/google-suite.mjs”]

# docker-compose.yml
version: ‘3.8’
services:
  google-mcp-server:
    build: .
    ports:
      - “127.0.0.1:3000:3000” # 只映射到本地
    environment:
      - GOOGLE_APPLICATION_CREDENTIALS=/run/secrets/google_credentials
      - TARGET_USER_EMAIL=${TARGET_EMAIL}
    secrets:
      - google_credentials
secrets:
  google_credentials:
    file: ./path/to/your/secret-key.json # 外部管理密钥文件

这样，密钥文件不会进入镜像层，更安全。通过 docker-compose up -d 即可启动。

5.3 与不同AI客户端的集成

google-suite-mcp 是一个标准MCP服务器，理论上可以接入任何支持MCP协议的客户端。

  • Claude Desktop ：目前对MCP支持最友好。你可以在Claude Desktop的设置中，配置本地MCP服务器。通常需要指定服务器类型（SSE或Stdio）和连接地址（如 http://localhost:3000/sse 或一个命令行命令）。
  • Cursor IDE / Windsurf ：这些AI编码助手也开始支持MCP，可以配置后让AI在编码时访问你的Google Drive文档作为上下文。
  • 自定义AI应用 ：如果你用LangChain、LlamaIndex等框架自建AI应用，可以使用MCP客户端库（如 @modelcontextprotocol/sdk ）来连接这个服务器，从而让你的Agent获得Google能力。

集成时，重点检查客户端的MCP配置方式，确保协议版本（如 2024-11-05 ）和传输方式（SSE/Stdio）与服务器端匹配。

6. 常见问题排查与性能优化

在实际部署和运行中，你可能会遇到以下问题：

6.1 认证与权限错误

错误现象 可能原因 解决方案
401 Unauthorized 或 Invalid Credentials 1. 密钥文件路径错误或内容损坏。
2. 服务账号未启用所需API。
3. 密钥文件对应的服务账号被禁用或删除。		 1. 检查 GOOGLE_APPLICATION_CREDENTIALS 环境变量或代码中加载密钥的路径。用 cat 命令确认文件可读且格式正确。
2. 回到GCP控制台，确认所有需要的API（Gmail, Drive, Calendar等）已启用。
3. 在GCP IAM中检查服务账号状态。
403 Permission Denied 或 Insufficient Permission 1. 域范围授权未完成或范围不匹配 （最常见）。
2. 服务账号没有被授予访问特定用户数据的权限（委派步骤未做）。
3. OAuth范围权限不足（例如，工具需要写权限，但只授权了只读）。		 1. 仔细核对 ：在GCP项目OAuth同意屏幕的“域范围授权”中授权的范围列表， 必须完全等于 在目标用户账号“安全”-“第三方应用访问”中为同一客户端ID授权的范围列表。多一个空格、少一个逗号都可能导致失败。建议直接复制粘贴。
2. 确保已登录目标邮箱，完成了客户端访问的授权步骤。
3. 检查工具需要的具体权限，并在授权范围中添加对应的、权限足够的Scope（如将 .../auth/gmail.readonly 改为 .../auth/gmail.modify ）。
Error: invalid_grant 服务器时间不同步，导致JWT令牌时间戳无效。 检查运行MCP服务器的机器时间是否准确。使用 ntpdate 或 timedatectl 同步时间。在Docker中，确保容器与宿主机时间同步。

6.2 连接与运行时错误

错误现象 可能原因 解决方案
MCP客户端无法连接到服务器 1. 服务器未启动或端口被占用。
2. 防火墙/安全组阻止了连接。
3. 客户端配置的地址或协议错误。		 1. 在服务器端运行 netstat -tulnp | grep :3000 检查端口监听状态。
2. 如果客户端不在本地，检查防火墙规则。 强烈建议仅限本地访问 。
3. 确认客户端配置的URL（如 http://localhost:3000/sse ）与服务器实际提供的端点一致。查看服务器启动日志。
工具调用超时或无响应 1. Google API调用本身较慢或遇到网络问题。
2. 查询结果集过大（如搜索所有邮件）。
3. MCP服务器进程卡死或内存不足。		 1. 在工具实现中添加合理的超时设置（如使用 Promise.race 或 AbortController ）。
2. 在工具调用时，始终使用 maxResults 等参数限制返回数量，实现分页查询。
3. 监控服务器资源使用情况。对于Node.js应用，可以使用 pm2 等进程管理器来保持稳定和自动重启。
AI客户端识别不到工具 1. MCP服务器启动时工具注册失败。
2. 客户端与服务器的MCP协议版本不兼容。
3. 服务器返回的工具声明格式有误。		 1. 查看服务器启动日志，确认是否有工具加载错误。检查 src/tools/ 下的模块是否有语法错误。
2. 检查 package.json 中MCP相关SDK的版本。尝试在客户端和服务器端使用相同的主要版本。
3. 使用简单的HTTP客户端（如curl）访问服务器的SSE端点或调用工具，查看原始返回数据是否符合MCP规范。

6.3 性能优化建议

  1. 实现请求缓存 ：对于读多写少的操作（如列出常用文件夹的文件、查询今天的日历），可以在MCP服务器层添加一个内存缓存（如 node-cache ）或Redis缓存。为相同的查询设置一个短的TTL（如30秒），可以大幅减少对Google API的调用，提升响应速度并节省配额。
  2. 批量操作支持 ：现有的工具可能是单次操作。如果AI经常需要执行“把这10封邮件都标记为已读”这样的任务，频繁调用API效率很低。可以考虑扩展工具，实现一个 gmail_batch_modify_messages 的工具，接受一个邮件ID数组。
  3. 异步与队列 ：对于耗时的写操作（如上传大文件到Drive），不要让HTTP请求一直等待。可以让工具立即返回一个“任务已接收”的响应，然后在后台异步处理，并通过其他方式（如另一个工具查询任务状态）通知客户端。这需要引入一个简单的任务队列（如 bull ）。
  4. 监控与告警 ：使用 PM2 、 Keymetrics 或云监控服务，监控MCP服务器的CPU、内存和错误率。为Google API的配额使用率设置告警（在GCP控制台可以设置），避免额度用尽导致服务中断。

7. 扩展开发：添加自定义工具

google-suite-mcp 项目的魅力在于其可扩展性。假设我们想添加一个操作Google Sheets的工具，用于读取表格数据。

第一步：创建工具文件 在 src/tools/ 目录下创建 sheets/ 文件夹，并新建 read-spreadsheet.mjs 。

// src/tools/sheets/read-spreadsheet.mjs
import { google } from ‘googleapis’;

/**
 * 读取Google Sheets指定范围的数据
 * @param {Object} params - 工具参数
 * @param {string} params.spreadsheetId - 表格ID
 * @param {string} params.range - A1表示法的范围，例如 ‘Sheet1!A1:D10’
 * @param {MCPRequest} request - MCP请求对象（用于访问认证客户端等）
 */
export async function readSpreadsheet(params, request) {
  const sheets = google.sheets({ version: ‘v4’, auth: request.context.googleAuth });

  try {
    const response = await sheets.spreadsheets.values.get({
      spreadsheetId: params.spreadsheetId,
      range: params.range,
    });

    const rows = response.data.values || [];
    // 将数据格式化为易读的文本，例如Markdown表格
    let markdownTable = ‘| ‘ + rows[0].join(‘ | ‘) + ‘ |\n’;
    markdownTable += ‘|’ + rows[0].map(() => ‘---’).join(‘|’) + ‘|\n’;
    for (let i = 1; i < rows.length; i++) {
      markdownTable += ‘| ‘ + rows[i].join(‘ | ‘) + ‘ |\n’;
    }

    return {
      content: [
        {
          type: ‘text’,
          text: `成功读取范围 \`${params.range}\` 的数据：\n\n${markdownTable}`,
        },
      ],
    };
  } catch (error) {
    console.error(‘读取Sheets出错:’, error);
    return {
      content: [{ type: ‘text’, text: `读取表格失败: ${error.message}` }],
      isError: true,
    };
  }
}

// 定义工具的元数据，供MCP服务器声明
export const toolDefinition = {
  name: ‘sheets_read_range’,
  description: ‘读取Google Sheets电子表格中指定范围的数据。’,
  inputSchema: {
    type: ‘object’,
    properties: {
      spreadsheetId: {
        type: ‘string’,
        description: ‘Google Sheets的ID，可以从URL中获取。’,
      },
      range: {
        type: ‘string’,
        description: ‘要读取的单元格范围，使用A1表示法，如 “Sheet1!A1:D10”。’,
      },
    },
    required: [‘spreadsheetId’, ‘range’],
  },
};

第二步：在主服务器中注册工具 打开 src/servers/google-suite.mjs ，找到工具注册的地方（通常是一个 tools 数组或循环注册的地方），添加新工具。

// 在文件顶部附近导入
import { readSpreadsheet, toolDefinition as sheetsReadTool } from ‘../tools/sheets/read-spreadsheet.mjs’;

// 在工具注册部分（例如，在某个setup函数中）
async function setupTools() {
  // ... 其他工具注册 ...
  server.tool(sheetsReadTool.name, sheetsReadTool.inputSchema, readSpreadsheet);
  // ... 其他工具注册 ...
}

第三步：更新OAuth范围 别忘了，新工具需要新的API权限。你需要更新服务账号的域范围授权，添加 https://www.googleapis.com/auth/spreadsheets.readonly （或 .readonly ）范围，并在目标用户账号中同样授权。

第四步：重启服务器并测试 重启MCP服务器，然后在你的AI客户端中，应该就能看到新工具 sheets_read_range 了。你可以尝试让AI：“帮我读取表格ID为 ‘abc123’ 中 ‘数据看板!A1:F20’ 这个范围的数据。”

通过这种方式，你可以将任何Google API（甚至是非Google的API）封装成MCP工具，极大地扩展了AI助手的能力边界。这不仅仅是连接了Google Workspace，更是为AI打开了一扇通往你所有数字资产的大门，而钥匙始终牢牢掌握在你手中，通过精细的权限和安全的协议来管控。

Logo
亚马逊云科技技术品牌专区

更多推荐

Fuzzapi项目概览：为什么它是REST API渗透测试的首选工具？

Fuzzapi是一款专为REST API渗透测试设计的强大工具，它基于API_Fuzzer gem构建，为开发人员和安全测试人员提供了高效、自动化的API漏洞检测方案。无论是小型应用还是大型系统，Fuzzapi都能帮助您快速发现潜在的安全风险，确保API接口的安全性。## 🚀 Fuzzapi的核心优势作为一款专注于REST API渗透测试的工具，Fuzzapi具有以下显著优势：###

avatar 亚马逊云科技技术品牌专区

3步掌握无线信号安全测试：Flipper Zero本田固件完整实战指南

无线安全测试是当今物联网安全领域的重要研究方向，而Flipper Zero本田固件为安全研究人员提供了深入了解无线信号重放攻击防护的绝佳平台。这款定制固件专门支持本田汽车钥匙（FCC ID: KR5V2X）的信号分析功能，通过CVE-2022-27254漏洞的实战研究，帮助技术人员掌握无线安全测试的核心技术。## 技术原理简析：无线信号重放攻击机制无线信号重放攻击的核心在于捕获合法设备发送

avatar 亚马逊云科技技术品牌专区

无需Arduino IDE！PSLab ESP01 Firmware的命令行编译与烧录技巧

PSLab ESP01 Firmware是一款专为ESP8266 ESP-01模块设计的固件，本文将详细介绍如何通过命令行工具快速完成固件的编译与烧录，无需依赖Arduino IDE，让开发过程更加高效便捷。## 📋 准备工作：环境与工具安装在开始操作前，需要确保系统中已安装以下工具：- **Python环境**：用于运行esptool.py工具- **esptool.py**：E

avatar 亚马逊云科技技术品牌专区