Google Docs MCP Server

通过 MCP (Model Context Protocol) 协议操作 Google 文档的 Server，支持 AI Agent 直接读写 Google 文档。

功能特性

• 📄 创建文档 - 快速创建新的 Google 文档
• 📖 读取文档 - 获取文档内容和结构
• ✏️ 编辑文档 - 插入、替换、删除文本
• 🎨 格式化 - 支持加粗、斜体、下划线、字体大小、颜色
• 📊 插入表格 - 在文档中添加表格
• 🔍 搜索文档 - 搜索 Google Drive 中的文档
• 📝 修改标题 - 修改文档标题（v1.0.6+）

快速开始

第一步：配置 Google Cloud

1. 创建项目并启用 API

1. 访问 Google Cloud Console
2. 创建新项目或选择现有项目
3. 启用 API：
   • Google Docs API
   • Google Drive API

2. 配置 OAuth 同意屏幕

1. 进入 API 和服务 > OAuth 同意屏幕
2. 选择用户类型：
   • 外部：任何人都可以使用（适合个人用户）
   • 内部：仅限组织内部使用（需要 Google Workspace）
3. 填写应用信息：
   • 应用名称：Google Docs MCP（或任意名称）
   • 用户支持邮箱：你的邮箱
   • 开发者联系邮箱：你的邮箱
4. 点击保存并继续
5. 添加权限范围（Scopes）：
   • 点击 添加或移除范围
   • 搜索并选择以下权限：
     • https://www.googleapis.com/auth/documents（Google Docs 完全访问）
     • https://www.googleapis.com/auth/drive（Google Drive 完全访问）
   • 点击 更新，然后 保存并继续
6. 添加测试用户（如果是外部应用）：
   • 点击 添加用户
   • 输入你的 Google 邮箱
   • 点击 保存并继续
7. 点击返回信息中心

3. 创建 OAuth 2.0 凭据

1. 进入 API 和服务 > 凭据
2. 点击 创建凭据 > OAuth 2.0 客户端 ID
3. 应用类型选择 桌面应用
4. 名称填写 Google Docs MCP
5. 点击 创建
6. 下载 client_secret.json（记录其中的 client_id 和 client_secret）

第二步：获取 Refresh Token

运行以下命令，按提示输入 Client ID 和 Client Secret：

npx @osulivan/google-docs-mcp --token

执行流程：

1. 输入 Client ID
2. 输入 Client Secret
3. 浏览器会自动打开 Google 授权页面（或复制链接到浏览器）
4. 登录 Google 账号并点击"允许"
5. 复制浏览器地址栏中的授权码
6. 粘贴授权码到终端
7. 获得 REFRESH_TOKEN，保存好这个值

第三步：配置 MCP Client

将以下配置添加到对应的 AI 工具中：

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@osulivan/google-docs-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "你的-client-id",
        "GOOGLE_CLIENT_SECRET": "你的-client-secret",
        "GOOGLE_REFRESH_TOKEN": "你的-refresh-token"
      }
    }
  }
}

Cursor

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@osulivan/google-docs-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "你的-client-id",
        "GOOGLE_CLIENT_SECRET": "你的-client-secret",
        "GOOGLE_REFRESH_TOKEN": "你的-refresh-token"
      }
    }
  }
}

Trae

编辑 ~/.trae/mcp.json：

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@osulivan/google-docs-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "你的-client-id",
        "GOOGLE_CLIENT_SECRET": "你的-client-secret",
        "GOOGLE_REFRESH_TOKEN": "你的-refresh-token"
      }
    }
  }
}

第四步：重启 AI 工具

重启 Claude/Cursor/Trae 后，AI 就可以使用 Google Docs 工具了！

使用示例

创建文档

帮我创建一个名为"项目计划"的 Google 文档

读取文档

请读取这个文档的内容：https://docs.google.com/document/d/DOCUMENT_ID/edit

编辑文档

在文档 DOCUMENT_ID 的末尾添加："会议时间：明天下午 2 点"

格式化文本

将文档 DOCUMENT_ID 中第 1-10 个字符设置为加粗

搜索文档

搜索标题包含"会议"的所有文档

修改文档标题

将文档 DOCUMENT_ID 的标题改为"新的文档标题"

CLI 命令

# 启动 MCP Server（stdio 模式）
npx @osulivan/google-docs-mcp

# 获取 Refresh Token
npx @osulivan/google-docs-mcp --token

# 显示帮助
npx @osulivan/google-docs-mcp --help

可用工具

| 工具名 | 描述 | 参数 | |--------|------|------| | docs_create | 创建文档 | title: string | | docs_get | 获取文档 | documentId: string | | docs_insert_text | 插入文本 | documentId, text, index? | | docs_replace_text | 替换文本 | documentId, text, newText | | docs_delete_text | 删除文本 | documentId, startIndex, endIndex | | docs_format_text | 格式化文本 | documentId, startIndex, endIndex, bold?, italic?, underline?, fontSize?, foregroundColor? | | docs_insert_table | 插入表格 | documentId, rows, columns, index? | | docs_search | 搜索文档 | query?, pageSize? | | docs_update_title | 修改文档标题 | documentId, newTitle |

环境变量

| 变量名 | 说明 | 必需 | |--------|------|------| | GOOGLE_CLIENT_ID | Google OAuth Client ID | ✅ | | GOOGLE_CLIENT_SECRET | Google OAuth Client Secret | ✅ | | GOOGLE_REFRESH_TOKEN | Google OAuth Refresh Token（长期有效） | ✅ |

常见问题

Token 会过期吗？

不会。GOOGLE_REFRESH_TOKEN 是长期有效的，配置一次即可长期使用。

• GOOGLE_REFRESH_TOKEN：长期有效（除非用户撤销授权）
• Access Token：1 小时过期，但 MCP Server 会自动刷新，用户无感知

什么情况下需要重新获取 Refresh Token？

| 情况 | 说明 | |------|------| | 首次使用 | 需要获取一次 | | 撤销授权 | 用户在 Google 账号设置中撤销了应用权限 | | 长期未使用 | 6 个月以上未使用，Google 自动清理 | | 安全原因 | Google 检测到异常活动 |

如何获取文档 ID？

Google 文档 URL 格式：

https://docs.google.com/document/d/DOCUMENT_ID/edit

示例：

https://docs.google.com/document/d/1aBcD_eFgHiJkLmN_opQr/edit
                        └────────────────────────┘
                              文档 ID

Refresh Token 可以在多台电脑使用吗？

可以。Refresh Token 绑定的是 Google 账号，不是设备。你可以在 A 电脑获取，在 B/C/D 电脑使用同一个 Refresh Token。

获取 Refresh Token 时出现 "invalid_client" 错误？

请检查：

1. Client ID 和 Client Secret 是否输入正确（不要有多余空格）
2. 是否在 Google Cloud Console 中创建了"桌面应用"类型的 OAuth 凭据
3. 是否已启用 Google Docs API 和 Google Drive API

技术栈

• TypeScript
• MCP Protocol
• Google Docs API
• Google Drive API

许可证

MIT