谷歌文档mcp

Name: 谷歌文档mcp
Author: a-bonus

作者：a-bonus151 星标更新：2025-10-30

安装使用来源：spider==github.com

项目介绍

Ultimate Google Docs & Drive MCP Server

演示动画

连接 Claude Desktop（或其他 MCP 客户端）到你的 Google 文档和 Google 驱动器！

🔥 查看 15 个强大的任务，你可以通过这个增强的服务器完成！ 📁 新功能： 完整的 Google 驱动器文件管理能力！

这个综合服务器使用模型上下文协议（MCP）和 fastmcp 库提供工具来读取、写入、格式化、构建 Google 文档，并管理整个 Google 驱动器。它充当一个强大的桥梁，允许像 Claude 这样的AI助手以编程方式与你的文档和文件进行交互，具有高级功能。

特性：

文档访问与编辑

读取文档： 使用 readGoogleDoc 读取内容（纯文本、JSON 结构或 Markdown）
追加到文档： 使用 appendToGoogleDoc 向文档添加文本
插入文本： 使用 insertText 在特定位置放置文本
删除内容： 使用 deleteRange 从文档中移除内容
标签支持： 使用 listDocumentTabs 和可选的 tabId 参数在多标签文档中进行读写操作

格式化与样式

文本格式化： 使用 applyTextStyle 应用丰富的样式（粗体、斜体、颜色等）
段落格式化： 使用 applyParagraphStyle 控制段落布局（对齐、间距等）
查找并格式化： 使用 formatMatchingText 按文本内容进行格式化（旧版支持）

文档结构

表格： 使用 insertTable 创建表格
分页符： 使用 insertPageBreak 插入分页符
图片： 使用 insertImageFromUrl 从 URL 插入图片，或使用 insertLocalImage 上传本地图片
实验性功能： 如 fixListFormatting 自动检测列表的工具

🆕 评论管理

列出评论： 使用 listComments 查看文档中的所有评论（显示作者、日期和引用文本）
获取评论详情： 使用 getComment 获取带有回复的具体评论
添加评论： 使用 addComment 创建新的锚定于文本的评论
回复评论： 使用 replyToComment 对现有评论进行回复
解决评论： 使用 resolveComment 将评论标记为已解决
删除评论： 使用 deleteComment 从文档中删除评论

🆕 Google 驱动器文件管理

文档发现： 使用 listGoogleDocs、searchGoogleDocs、getRecentGoogleDocs 查找和列出文档
文档信息： 使用 getDocumentInfo 获取详细的元数据
文件夹管理： 创建文件夹（createFolder）、列出内容（listFolderContents）、获取信息（getFolderInfo）
文件操作： 移动（moveFile）、复制（copyFile）、重命名（renameFile）、删除（deleteFile）
文档创建： 创建新文档（createDocument）或从模板创建（createFromTemplate）

集成

Google 认证： 使用完整的驱动器访问权限进行安全的 OAuth 2.0 认证
MCP 兼容： 设计用于与 Claude 和其他 MCP 客户端一起使用
VS Code 集成： 设置指南用于 VS Code MCP 扩展

前提条件

开始之前，请确保你拥有以下条件：

Node.js 和 npm： 在计算机上安装了最新版本的 Node.js（包括 npm）。可以从 nodejs.org 下载。（推荐版本 1.8 或更高）。
Git： 克隆此仓库所需的。(下载 Git)。
Google 账户： 拥有或有权访问你想与其交互的 Google 文档的账户。
命令行熟悉度： 基本舒适地使用终端或命令提示符（如 macOS/Linux 的 Terminal，或 Windows 的 Command Prompt/PowerShell）。
Claude Desktop（可选）： 如果你的目标是将此服务器连接到 Claude，则需要安装 Claude Desktop 应用程序。

设置说明

按照以下步骤仔细操作，以运行自己的服务器实例。

第一步：Google Cloud 项目及凭证（重要部分！）

此服务器需要权限代表你与 Google API 通信。你需要创建只有你的服务器会使用的特殊“密钥”（凭证）。

前往 Google Cloud 控制台： 打开你的网络浏览器，前往 Google Cloud 控制台。你可能需要用你的 Google 账户登录。
创建或选择一个项目：
- 如果没有项目，点击顶部附近的项目下拉菜单，选择“新建项目”。给它起个名字（例如，“我的 MCP 文档服务器”），然后点击“创建”。
- 如果已有项目，可以选择一个或创建一个新的。
启用 API： 你需要打开此服务器使用的特定 Google 服务。
- 在顶部的搜索栏中，键入“API和服务”，然后选择“库”。
- 搜索“Google 文档 API”，点击它，然后点击“启用”按钮。
- 搜索“Google 驱动器 API”，点击它，然后点击“启用”按钮（通常需要找到文件或权限）。
配置 OAuth 同意屏幕： 此屏幕告诉用户（通常是您自己）您的应用程序想要获得哪些权限。
- 在左侧菜单中，点击“API和服务”->“OAuth 同意屏幕”。
- 选择用户类型：选择“外部”，然后点击“创建”。
- 填写应用信息：
  - 应用名称： 给它一个用户可以看到的名字（例如，“Claude 文档 MCP 访问”）。
  - 用户支持电子邮件： 选择您的电子邮件地址。
  - 开发者联系信息： 输入您的电子邮件地址。
- 点击“保存并继续”。
- 范围： 点击“添加或移除范围”。搜索并添加以下范围：
  - https://www.googleapis.com/auth/documents（允许读写文档）
  - https://www.googleapis.com/auth/drive.file（允许访问应用程序打开/创建的特定文件）
  - 点击“更新”。
- 点击“保存并继续”。
- 测试用户： 点击“添加用户”。输入您登录时使用的同一 Google 电子邮件地址。点击“添加”。这允许您在“测试”模式下使用该应用程序。
- 点击“保存并继续”。查看摘要并点击“返回仪表板”。
创建凭证（密钥！）：
- 在左侧菜单中，点击“API和服务”->“凭证”。
- 点击顶部的“+ 创建凭证”并选择“OAuth 客户端 ID”。
- 应用类型： 从下拉菜单中选择“桌面应用”。
- 名称： 给它一个名字（例如，“MCP 文档桌面客户端”）。
- 点击“创建”。
⬇️ 下载凭证文件： 会弹出一个框显示您的客户端 ID。点击“下载 JSON”按钮。
- 保存此文件。它可能会被命名为类似于 client_secret_....json。
- 重要： 将下载的文件重命名为 credentials.json。
⚠️ 安全警告： 将此 credentials.json 文件视为密码！不要公开分享，且永远不要将其提交到 GitHub。任何人拥有此文件都可能假装是您的应用程序（尽管他们仍需用户同意才能访问数据）。

第二步：获取服务器代码

克隆存储库： 打开您的终端/命令提示符并运行：

git clone https://github.com/a-bonus/google-docs-mcp.git mcp-googledocs-server

导航到目录：
```
cd mcp-googledocs-server
```
放置凭证： 将您下载并重命名的 credentials.json 文件（来自第 1.6 步）直接移动或复制到此 mcp-googledocs-server 文件夹中。

第三步：安装依赖项

您的服务器需要一些在 package.json 文件中指定的帮助库。

在您的终端（确保您在 mcp-googledocs-server 目录内），运行：
```
npm install
```
这将下载并安装所有必要的包到 node_modules 文件夹中。

第四步：编译服务器代码

服务器是用 TypeScript（.ts）编写的，但我们需要将其编译成 JavaScript（.js），以便 Node.js 可以直接运行。

在您的终端中，运行：
```
npm run build
```
这将使用 TypeScript 编译器（tsc）创建一个包含编译后的 JavaScript 文件的 dist 文件夹。

第五步：首次运行及 Google 授权（仅一次）

现在您需要手动运行服务器一次，以授予其访问您的 Google 账户数据的权限。这将创建一个 token.json 文件，保存您的授权许可。

在您的终端中，使用 node 运行已编译的服务器：
```
node ./dist/server.js
```
观察终端： 脚本将打印：
- 状态消息（如“尝试授权...”）。
- “通过访问此网址授权此应用：”消息后跟一个长 https://accounts.google.com/... URL。
浏览器授权：
- 从终端复制整个长 URL。
- 将 URL 粘贴到您的网络浏览器中并按 Enter。
- 使用在第 1.4 步中作为测试用户添加的相同 Google 账户登录。
- Google 将显示一个屏幕，询问您的应用（“Claude 文档 MCP 访问”或类似名称）访问 Google 文档/驱动器的权限。查看并点击“允许”或“授予”。
获取授权码：
- 点击允许后，您的浏览器可能会尝试重定向到 http://localhost 并显示“无法连接到该站点”的错误。这是正常的！
- 仔细查看浏览器地址栏中的 URL。它看起来像 http://localhost/?code=4/0Axxxxxxxxxxxxxx&scope=...
- 复制 code= 和 &scope 部分之间的长字符串字符。这是您的单次使用授权码。
粘贴代码到终端： 回到等待脚本的终端（“在此页面输入代码：”）。粘贴您刚刚复制的代码。
按 Enter。
成功！ 脚本应打印：
- “认证成功！”
- “令牌存储到.../token.json”
- 然后启动并可能打印“等待通过 stdio 连接的 MCP 客户端...”或类似内容，然后退出（或您可以按 Ctrl+C 停止它）。
✅ 检查： 您应该现在看到 mcp-googledocs-server 文件夹中的一个名为 token.json 的新文件。
⚠️ 安全警告： 此 token.json 文件包含允许服务器无需再次请求即可访问您的 Google 账户的关键。像密码一样保护它。不要将其提交到 GitHub。包含的 .gitignore 文件应自动防止这种情况。

第六步：配置 Claude Desktop（可选）

如果您想使用此服务器与 Claude Desktop，您需要告诉 Claude 如何运行它。

找到绝对路径： 您需要服务器代码的完整路径。
- 在您的终端中，确保仍然在 mcp-googledocs-server 目录内。
- 运行 pwd 命令（在 macOS/Linux 上）或 cd（在 Windows 上，只需显示路径）。
- 复制完整路径（例如，/Users/yourname/projects/mcp-googledocs-server 或 C:\Users\yourname\projects\mcp-googledocs-server）。
定位 mcp_config.json： 找到 Claude 的配置文件：
- macOS： ~/Library/Application Support/Claude/mcp_config.json（您可能需要使用 Finder 的“转到”->“转到文件夹...”菜单并粘贴 ~/Library/Application Support/Claude/）
- Windows： %APPDATA%\Claude\mcp_config.json（将 %APPDATA%\Claude 粘贴到文件资源管理器的地址栏中）
- Linux： ~/.config/Claude/mcp_config.json
- 如果不存在 Claude 文件夹或 mcp_config.json 文件，请创建它们。
编辑 mcp_config.json： 在文本编辑器中打开文件。添加或修改 mcpServers 部分如下，将 /PATH/TO/YOUR/CLONED/REPO 替换为您在第 6.1 步中复制的实际绝对路径：
```
{
  "mcpServers": {
    "google-docs-mcp": {
      "command": "node",
      "args": [
        "/PATH/TO/YOUR/CLONED/REPO/mcp-googledocs-server/dist/server.js"
      ],
      "env": {}
    }
    // 如果定义了其他服务器，请在这里添加逗号
  }
  // 其他 Claude 设置可能在这里
}
```
- 确保 args 中的路径正确且为绝对路径！
- 如果文件已经存在，请小心地将此条目合并到现有的 mcpServers 对象中。确保 JSON 是有效的（检查逗号！）。
保存 mcp_config.json。
重启 Claude Desktop： 完全关闭 Claude 并重新打开它。

使用 Claude Desktop

一旦配置好，您应该能够在与 Claude 的聊天中使用这些工具：

“使用 google-docs-mcp 服务器读取 ID 为 YOUR_GOOGLE_DOC_ID 的文档。”
“你能得到 Google 文档 YOUR_GOOGLE_DOC_ID 的内容吗？”
“使用 google-docs-mcp 工具将‘这是由 Claude 添加的！’追加到文档 YOUR_GOOGLE_DOC_ID。”

处理标签

Google 文档现在支持多标签文档。此 MCP 服务器提供了处理标签的完整支持：

列出标签：

“使用 listDocumentTabs 工具列出文档 YOUR_GOOGLE_DOC_ID 中的所有标签。”
“显示文档 YOUR_GOOGLE_DOC_ID 的标签结构及其内容摘要。”

从特定标签读取：

“使用 readGoogleDoc 工具从文档 YOUR_GOOGLE_DOC_ID 的标签 TAB_ID 读取内容。”
“获取文档 YOUR_GOOGLE_DOC_ID 的标签 TAB_ID 的 Markdown 内容。”

向特定标签写入：

“将‘新内容’追加到文档 YOUR_GOOGLE_DOC_ID 的标签 TAB_ID。”
“在文档 YOUR_GOOGLE_DOC_ID 的标签 TAB_ID 的索引 100 处插入文本。”
“删除文档 YOUR_GOOGLE_DOC_ID 的标签 TAB_ID 的索引 50-100 处的内容。”

注意： 以下工具支持可选的 tabId 参数：

readGoogleDoc - 从特定标签读取
appendToGoogleDoc - 追加到特定标签
insertText - 向特定标签插入文本
deleteRange - 从特定标签删除内容

当未指定 tabId 时，操作针对第一个标签（或对于没有标签的老文档，针对旧文档正文）。

高级用法示例：

文本样式： “使用 applyTextStyle 将文档 YOUR_GOOGLE_DOC_ID 中的‘重要部分’文本设为粗体和红色（#FF0000）。”
段落样式： “使用 applyParagraphStyle 将文档 YOUR_GOOGLE_DOC_ID 中包含‘此处标题’的段落居中对齐。”
表格创建： “使用 insertTable 工具在文档 YOUR_GOOGLE_DOC_ID 的索引 500 处插入一个 3x4 表格。”
图片插入： “使用 insertImageFromUrl 从 ‘https://example.com/image.png’ 插入一张图片到文档 YOUR_GOOGLE_DOC_ID 的索引 100 处。”
本地图片上传： “使用 insertLocalImage 上传 ‘/path/to/image.jpg’ 并将其插入到文档 YOUR_GOOGLE_DOC_ID 的索引 200 处。”
旧版格式化： “使用 formatMatchingText 查找文档 YOUR_GOOGLE_DOC_ID 中的第二个‘项目阿尔法’实例并将其设为蓝色（#0000FF）。”

记得将 YOUR_GOOGLE_DOC_ID 替换为实际的 Google 文档 URL 中的 ID（位于 /d/ 和 /edit 之间的长字符串）。

Claude 将根据您提供的命令自动在后台启动您的服务器。您不需要再手动运行 node ./dist/server.js。

图片插入

此服务器提供了两种将图片插入 Google 文档的方法：

1. 从公共 URL 插入（`insertImageFromUrl`）

直接从一个可公开访问的 URL 插入图片。图片 URL 必须无需身份验证即可访问。

参数：

documentId：Google 文档 ID
`