Claude MCP x Google Docs

终极 Google Docs MCP 服务器

将 Claude Desktop（或其他 MCP 客户端）连接到您的 Google Docs！

🔥查看您可以使用此增强型服务器完成的10 项强大任务！

这款增强型服务器使用模型上下文协议 (MCP) 和fastmcp库，提供用于读取、写入、格式化和构建 Google 文档的全面工具。它充当着一座强大的桥梁，让像 Claude 这样的 AI 助手能够以编程方式使用高级功能与您的文档进行交互。

特征：

文档访问

• **读取文档：**使用readGoogleDoc读取内容（纯文本、JSON 结构或 markdown）
• **附加到文档：**使用appendToGoogleDoc将文本添加到文档
• **插入文本：**使用insertText将文本放置在特定位置
• **删除内容：**使用deleteRange从文档中删除内容

格式和样式

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

文档结构

• **表：**使用insertTable创建表
• **分页符：**使用insertPageBreak插入分页符
• 实验性功能： fixListFormatting等用于自动列表检测的工具

一体化

• **Google 身份验证：**安全 OAuth 2.0 身份验证
• 符合 MCP 标准：专为与 Claude 和其他 MCP 客户端配合使用而设计

先决条件

在开始之前，请确保您已：

1. **Node.js 和 npm：**您的计算机上已安装最新版本的 Node.js（包含 npm）。您可以从nodejs.org下载。（建议使用 18 或更高版本）。
2. **Git：**克隆此存储库所需。（下载 Git ）。
3. **Google 帐户：**拥有或有权访问您想要与之交互的 Google 文档的帐户。
4. **命令行熟悉度：**能够基本熟练地使用终端或命令提示符（例如 macOS/Linux 上的终端，或 Windows 上的命令提示符/PowerShell）。
5. **Claude Desktop（可选）：**如果您的目标是将此服务器连接到 Claude，则需要安装 Claude Desktop 应用程序。

设置说明

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

步骤 1：Google Cloud 项目和凭证（重要部分！）

此服务器需要获得代表您与 Google API 通信的权限。您需要创建只有您的服务器才能使用的特殊“密钥”（凭据）。

1. **前往 Google Cloud Console：**打开您的网络浏览器并前往Google Cloud Console 。您可能需要使用您的 Google 帐户登录。
2. 创建或选择项目：
   • 如果您还没有项目，请点击顶部附近的项目下拉菜单，选择“新建项目”。输入项目名称（例如，“我的 MCP 文档服务器”），然后点击“创建”。
   • 如果您有现有项目，则可以选择一个或创建一个新项目。
3. **启用 API：**您需要打开此服务器使用的特定 Google 服务。
   • 在顶部的搜索栏中，输入“API 和服务”并选择“库”。
   • 搜索“ Google Docs API ”并点击。然后点击“启用”按钮。
   • 搜索“ Google Drive API ”并点击。然后点击“启用”按钮（通常用于查找文件或权限）。
4. **配置 OAuth 同意屏幕：**此屏幕告诉用户（通常只有您）您的应用需要什么权限。
   • 在左侧菜单中，点击“API 和服务”->“ OAuth 同意屏幕”。
   • 选择用户类型：选择“外部”，然后单击“创建”。
   • 填写应用信息：
     • **应用程序名称：**为其指定一个用户将看到的名称（例如，“Claude Docs MCP Access”）。
     • **用户支持电子邮件：**选择您的电子邮件地址。
     • **开发者联系信息：**输入您的电子邮件地址。
   • 单击“保存并继续”。
   • **范围：**点击“添加或删除范围”。搜索并添加以下范围：
     • https://www.googleapis.com/auth/documents （允许读取/写入文档）
     • https://www.googleapis.com/auth/drive.file （允许访问应用程序打开/创建的特定文件）
     • 点击“更新”。
   • 单击“保存并继续”。
   • **测试用户：**点击“添加用户”。输入您登录时使用的 Google 电子邮件地址。点击“添加”。这样您就可以在应用处于“测试”模式时使用它。
   • 点击“保存并继续”。查看摘要，然后点击“返回仪表板”。
5. 创建凭证（密钥！）：
   • 在左侧菜单中，单击“API 和服务”->“凭据”。
   • 单击顶部的“ + 创建凭据”，然后选择“ OAuth 客户端 ID ”。
   • **应用程序类型：**从下拉菜单中选择“桌面应用程序”。
   • **名称：**为其命名（例如，“MCP Docs Desktop Client”）。
   • 点击“创建”。
6. **⬇️ 下载凭证文件：**将会弹出一个框，显示您的客户端 ID。点击“下载 JSON ”按钮。
   • 保存此文件。它的名称可能类似于client_secret_....json 。
   • **重要提示：**将下载的文件重命名为credentials.json 。
7. ⚠️**安全警告：请将此credentials.json文件视为密码！请勿公开分享，也切勿将其提交到 GitHub。**任何拥有此文件的人都可能冒充您的应用程序（尽管他们仍然需要用户同意才能访问数据）。

第 2 步：获取服务器代码

1. **克隆存储库：**打开终端/命令提示符并运行：
   git clone https://github.com/a-bonus/google-docs-mcp.git mcp-googledocs-server
2. 导航到目录：
   cd mcp-googledocs-server
3. **放置凭证：**将您下载并重命名的credentials.json文件（从步骤 1.6 开始）直接移动或复制到此mcp-googledocs-server文件夹中。

步骤3：安装依赖项

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

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

步骤 4：构建服务器代码

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

1. 在你的终端中运行：
   npm run build
   这使用 TypeScript 编译器（ tsc ）创建一个包含已编译 JavaScript 文件的dist文件夹。

步骤 5：首次运行和 Google 授权（仅一次）

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

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

步骤 6：配置 Claude 桌面（可选）

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

1. **查找您的绝对路径：**您需要服务器代码的完整路径。
   • 在您的终端中，确保您仍在mcp-googledocs-server目录中。
   • 运行pwd命令（在 macOS/Linux 上）或cd （在 Windows 上，仅显示路径）。
   • 复制完整路径（例如， /Users/yourname/projects/mcp-googledocs-server或C:\Users\yourname\projects\mcp-googledocs-server ）。
2. **找到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文件不存在，请创建它们。
3. **编辑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": {} } // Add commas here if you have other servers defined } // Other Claude settings might be here }
   • 确保"args"中的路径正确且绝对！
   • 如果文件已存在，请仔细将此条目合并到现有的mcpServers对象中。确保 JSON 格式有效（检查逗号！）。
4. 保存mcp_config.json 。
5. **重新启动 Claude Desktop：**完全关闭 Claude 并重新打开它。

与 Claude Desktop 一起使用

配置完成后，您应该能够在与 Claude 的聊天中使用这些工具：

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

高级用法示例：

• 文本样式：“使用applyTextStyle将文档YOUR_GOOGLE_DOC_ID中的文本‘重要部分’设为粗体和红色（#FF0000）。”
• 段落样式：“使用applyParagraphStyle将包含‘此处标题’的段落在YOUR_GOOGLE_DOC_ID文档中居中对齐。”
• 表格创建：“使用insertTable工具在文档YOUR_GOOGLE_DOC_ID的索引 500 处插入一个 3x4 表格。”
• 旧格式：“使用formatMatchingText查找文档YOUR_GOOGLE_DOC_ID中的‘Project Alpha’的第二个实例，并将其变为蓝色（#0000FF）。”

请记住将YOUR_GOOGLE_DOC_ID替换为 Google Doc 网址中的实际 ID（ /d/和/edit之间的长字符串）。

需要时，Claude 会使用你提供的命令在后台自动启动服务器。你无需再手动运行node ./dist/server.js 。

安全与令牌存储

• **.gitignore ：**此存储库包含一个.gitignore文件，它可以防止您意外提交敏感的credentials.json和token.json文件。请勿从.gitignore中删除这几行。
• **令牌存储：**此服务器将 Google 授权令牌 ( token.json ) 直接存储在项目文件夹中，以便于设置。在生产环境或对安全性要求更高的环境中，请考虑以更安全的方式存储此令牌，例如使用系统钥匙串、加密文件或专用密钥管理服务。

故障排除

• 克劳德显示“失败”或“无法附加”：
  • 仔细检查mcp_config.json中的绝对路径。
  • 确保您成功运行npm run build并且dist文件夹存在。
  • 尝试在终端中手动运行mcp_config.json中的命令： node /PATH/TO/YOUR/CLONED/REPO/mcp-googledocs-server/dist/server.js 。查看是否打印了任何错误。
  • 检查 Claude Desktop 日志（参见官方 MCP 调试指南）。
  • 确保服务器代码中的所有console.log状态消息都更改为console.error 。
• Google 授权错误：
  • 确保您启用了正确的 API（文档、云端硬盘）。
  • 确保您在 OAuth 同意屏幕上将您的电子邮件添加为测试用户。
  • 验证credentials.json文件是否正确放置在项目根目录中。

执照

本项目遵循 MIT 许可证 - 详情请参阅LICENSE文件。（注意：您需要将包含 MIT 许可证文本的LICENSE文件添加到您的代码库中。）