gdoc mcp
一个MCP服务器，允许Claude使用markdown语法阅读和编辑谷歌文档、表格、日历和Gmail。
特性
谷歌文档
- 以标记方式阅读文档（粗体、斜体、下划线、删除线、链接、标题、列表、表格）
- 使用markdown格式编辑文本(
**bold**,*italic*,underline,~~strikethrough~~,[link](url)) - 使用正则表达式模式和上下文进行搜索
- 列出、创建和复制文档
谷歌表格
- 将表格视为标记表
- 编辑单元格（支持公式）
- 添加行
- 添加新工作表（选项卡）
- 获取工作表元数据
- 创建和复制电子表格
谷歌日历
- 列出您有权访问的所有日历（拥有、共享、订阅）
- 列出具有日期范围和搜索筛选的事件
- 创建、更新和删除事件
- 全天和定时活动
- 自然语言事件创作（如“明天中午午餐”）
Gmail
- 使用Gmail搜索语法列出和搜索电子邮件
- 读取完整消息内容（纯文本提取）
- 创建带有可选文件附件的草稿（新建或回复）——草稿不会被发送
- 更新和删除现有草稿
- 用原始对话正确回复草稿
- 列出电子邮件附件并将其保存到本地文件
并发安全
- 编辑前需要阅读（确保您已经看到内容）
- 基于文本的验证（在替换之前确认目标文本存在）
- 公式感知工作表编辑（检测并发公式更改）
- 彩色差异输出准确显示了变化的内容
安装
npm install && npm run build认证
使用OAuth 2.0对所有Google Workspace API进行身份验证。
1.创建OAuth凭据
- 首选 console.cloud.google.com
- 创建项目（或选择现有项目）
- 启用这些API（API和服务>启用API）：
- 谷歌文档API - 谷歌网页API - Google Drive API - 谷歌日历API - Gmail API
- 配置OAuth同意屏幕：
- 用户类型：外部 - 将您的电子邮件添加为测试用户
- 创建凭据：
- API和服务>凭据>创建凭据>OAuth 2.0客户端ID - 应用程序类型： 桌面应用程序 - 下载JSON文件
2.身份验证
# Save the client secret:
mkdir -p ~/.config/gdoc-mcp
cp ~/Downloads/client_secret_*.json ~/.config/gdoc-mcp/client_secret.json
# Run the OAuth flow (opens browser):
npm run auth这将打开您的浏览器以获得Google OAuth同意，然后将令牌保存到 ~/.config/gdoc-mcp/tokens.json.
SSH/无头环境： 身份验证URL将打印到终端。在任何浏览器中访问它。如果localhost重定向失败，请从浏览器的地址栏复制URL并将其粘贴回终端。
令牌自动刷新。你只需要重新运行 npm run auth 如果您撤销访问权限或刷新令牌过期。
疑难解答：“API尚未在项目中使用”或“已禁用”
如果您看到以下错误：
Google Docs API has not been used in project 454715852682 before or it is disabled.GCP项目上已禁用所需的Google API。使用gcloud CLI重新启用它们：
gcloud services enable \
docs.googleapis.com \
drive.googleapis.com \
sheets.googleapis.com \
calendar-json.googleapis.com \
gmail.googleapis.com \
--project=panozzaj-general或者在 谷歌云控制台.
重新启用后，MCP服务器应立即工作（无需重新启动）。如果你也必须重新跑步 npm run auth，您需要重新启动MCP服务器（例如。， /reload 在Claude Code中），因此它会获取新的令牌。
故障排除：“OAuth令牌已过期或被吊销”
cd ~/Documents/dev/gdoc-mcp
npm run auth # Opens browser for OAuth consent然后重新启动MCP服务器(/reload 在Claude Code中），因此它从以下位置加载新令牌 ~/.config/gdoc-mcp/tokens.json.
配置
添加到您的Claude MCP配置中：
{
"mcpServers": {
"gdoc": {
"command": "node",
"args": ["/path/to/gdoc-mcp/dist/server.js"]
}
}
}工具
谷歌文档
| 工具 | 说明 |
|---|---|
gdoc_read | 阅读谷歌文档作为标记 |
gdoc_edit | 使用markdown替换文本，或附加空的old_text（需要先读取） |
gdoc_search | 使用正则表达式搜索文档内容 |
gdoc_list | 列出最近的谷歌文档 |
gdoc_info | 获取文档元数据 |
gdoc_create | 创建新的空白文档 |
gdoc_copy | 复制现有文档 |
谷歌表格
| 工具 | 说明 |
|---|---|
gsheet_read | 将谷歌表格作为标记表阅读 |
gsheet_edit | 更新工作表中的单元格 |
gsheet_append | 将行附加到工作表 |
gsheet_info | 获取电子表格元数据 |
gsheet_create | 创建新的空白电子表格 |
gsheet_copy | 复制现有电子表格 |
gsheet_add_tab | 在电子表格中添加新选项卡 |
gsheet_clone_tab | 克隆/复制电子表格中的选项卡 |
gsheet_delete_tab | 从电子表格中删除选项卡 |
谷歌日历
| 工具 | 说明 |
|---|---|
gcal_list_calendars | 列出您有权访问的所有日历 |
gcal_list_events | 列出事件（支持日期范围、搜索） |
gcal_read_event | 获取单个事件的完整详细信息 |
gcal_create_event | 创建新事件（定时或全天） |
gcal_update_event | 更新现有事件 |
gcal_delete_event | 删除事件 |
gcal_quick_add_event | 从自然语言创建事件 |
Gmail
| 工具 | 说明 |
|---|---|
gmail_list_messages | 使用Gmail搜索语法搜索/列出电子邮件 |
gmail_read_message | 按ID读取完整消息内容 |
gmail_list_message_attachments | 列出邮件中的附件 |
gmail_save_attachment | 将附件保存到本地文件 |
gmail_list_drafts | 列出现有电子邮件草稿 |
gmail_create_draft | 创建带有可选附件的新草稿 |
gmail_create_reply_draft | 创建线程回复草稿（未发送） |
gmail_update_draft | 更新现有草稿 |
gmail_delete_draft | 永久删除草稿 |
与其他MCP服务器的比较
大多数Google Docs MCP服务器没有并发保护，这使得它们在并发编辑文档时容易发生无声数据丢失。
| 存储库 | 并发控制 |
|---|---|
| gdoc mcp （本项目） | 基于文本的验证 |
| a-bonus/google-docs mcp | 无（基于索引的操作） |
| phact/mcp谷歌文档 | 无（先读后写比赛） |
| Meerkats Ai/谷歌文档mcp服务器 | 无 |
| VolksRat71/谷歌工作区mcp | 存在修订工具，但不用于编辑 |
| piotr agier/谷歌驱动器mcp | 无 |
| isaacphi/mcp gdrive | 无（仅限工作表） |
gdoc-mcp如何处理并发：
gdoc_read必须首先调用（缓存修订，确保您已经看到内容）gdoc_edit获取当前文档状态- 验证
old_text文档中仍存在 - 如果找到，则继续编辑；如果没有，则显示要重新读取的消息错误
这可以防止无声覆盖，同时允许对文档的不同部分进行并发编辑。
局限性
- 编辑范围：段落和表格单元格中的文本可以使用内联格式进行编辑。标题、列表和图像是可读的，但不能直接编辑。
- 复杂的格式：颜色、字体和嵌套样式不会保留。
- 日历：尚未支持重复事件管理。
- Gmail：草稿和只读-无发送功能（出于安全考虑，按设计）。仅限纯文本草稿。
发展
npm run dev # Watch mode (recompile on change)
npm test # Run tests
npm run test:watch # Watch mode tests
npm run build # One-time build
npm run auth # Re-run OAuth flow许可证
麻省理工学院