使用说明

谷歌MCP服务器

生产级MCP服务器，可与Gmail、日历、表格、文档和驱动器完全集成Google Workspace。

特性

28工具 全面访问谷歌工作区
生产级错误处理 自动重试
二进制文件支持 用于驱动操作
费率限制处理 指数回退
输入验证 以及查询净化
OAuth 2.0 具有自动令牌刷新功能

支持服务列表

Gmail（7个工具）

gmail_search -使用高级查询搜索电子邮件
gmail_send -发送带有附件的电子邮件（默认情况下为模拟运行）
gmail_reply_latest -对最新帖子的回复
gmail_create_draft -创建电子邮件草稿
gmail_get_thread -获取完整的线程对话
gmail_label_threads -应用/删除标签
gmail_search_unread_from -查找发件人/域中的未读邮件

日历（6工具）

calendar_get_agenda -获取即将举行的活动
calendar_create_meeting -使用Google Meet创建日历事件
calendar_quick_add -自然语言事件创建
calendar_reschedule_event -将事件移至新时代
calendar_delete_event -删除日历事件
calendar_find_slots -查找可用的时间段

表格（5个工具）

sheets_create -创建新的电子表格
sheets_read -读取电子表格数据
sheets_append -将行附加到工作表
sheets_update -更新特定单元格
sheets_search -按名称查找电子表格

文档（4个工具）

docs_create -创建新文档
docs_read -读取文档内容
docs_update -在文档中添加/编辑文本
docs_search -按名称查找文档

驱动器（6个工具）

drive_list -列出文件夹中的文件
drive_search -搜索所有文件
drive_download -下载文件（文本/二进制，最大10MB）
drive_upload -从路径/content/b64上传文件
drive_share -与用户共享文件
drive_create_folder -创建文件夹

安装

快速开始

10分钟后开始 -看 QUICKSTART.md

先决条件

Node.js>=20.0.0
使用OAuth凭据的谷歌云项目（在QUICKSTART.md中设置5分钟）

从npm安装

npm install -g @chieflatif/google-mcp

验证

GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com" \
GOOGLE_CLIENT_SECRET="your-client-secret" \
npx @chieflatif/google-mcp setup-oauth

按照浏览器提示授予权限。令牌保存到 ~/.mcp-google/tokens.json.

就是这样！ 现在在下面配置您的AI客户端。

使用AI客户端

克劳德桌面

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

{
  "mcpServers": {
    "google-mcp": {
      "command": "npx",
      "args": ["-y", "@chieflatif/google-mcp"],
      "env": {
        "MCP_CORE_TOOLS": "1",
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

光标

编辑 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "google-mcp": {
      "command": "npx",
      "args": ["-y", "@chieflatif/google-mcp"],
      "env": {
        "MCP_CORE_TOOLS": "1",
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

ChatGPT桌面

编辑ChatGPT桌面配置文件：

macOS: ~/Library/Application Support/ChatGPT/config.json
视窗: %APPDATA%\ChatGPT\config.json

{
  "mcpServers": {
    "google-mcp": {
      "command": "npx",
      "args": ["-y", "@chieflatif/google-mcp"],
      "env": {
        "MCP_CORE_TOOLS": "1",
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

重新启动AI客户端 并开始通过自然语言使用Google Workspace：

“今天我的日历上有什么？”
“阅读我的主任务列表电子表格”
“发送电子邮件至colleague@example.com关于会议”
“创建一个名为“项目计划”的新文档”
“在我的硬盘中搜索Q4计划文档”

配置模式

核心模式（推荐）

"MCP_CORE_TOOLS": "1"

24个基本工具，用于对所有服务进行完全读/写访问

全模式（所有工具）

// Remove MCP_CORE_TOOLS or set to "0"

28个工具，包括高级日历功能

最小模式（最快）

"MCP_MINIMAL_TOOLS": "1"

5个仅用于基本读取操作的工具

错误处理

所有工具都返回标准化的错误响应：

{
  status: 'error',
  error: 'Human-readable message',
  code: 'ERROR_CODE',
  retryable: boolean,
  details: {...}
}

错误代码

RATE_LIMIT_EXCEEDED -稍后重试（自动重试3次）
AUTH_FAILED -与Google重新进行身份验证
NOT_FOUND -资源ID无效
INVALID_REQUEST -检查参数
SERVER_ERROR -Google服务器问题（自动重试）
FILE_TOO_LARGE -文件超过10MB限制

安全特性

✅ 所有参数的输入验证
✅ 查询消毒以防止注射
✅ OAuth作用域仅限于所需权限
✅ 自动刷新本地存储的令牌
✅ 破坏性操作的干运行模式
✅ 防止内存问题的文件大小限制

故障排除

身份验证错误

# Re-run OAuth setup
GOOGLE_CLIENT_ID="..." GOOGLE_CLIENT_SECRET="..." \
node scripts/setup-oauth.js

速率限制错误

服务器会自动以指数回退方式重试。如果持续存在：

请求之间等待60秒
检查谷歌工作区配额

二进制文件下载问题

大于10MB的文件将返回 FILE_TOO_LARGE 错误。对于大文件：

使用谷歌云端硬盘网络界面
或者分成小块

发展

# Run in development mode
npm run dev

# Build TypeScript
npm run build

# Test authentication
npm run test:auth

API限值

Google Workspace API配额（每个项目）：

Gmail：2500个配额单位/天
日历：1000000次请求/天
页数：300次/分钟
文件：300个请求/分钟
驱动器：12000个请求/分钟

服务器实现了自动重试，并对速率限制进行指数回退。

许可证

麻省理工学院

贡献

问题和PR欢迎！这是供公众使用的生产级软件。

支持

Google Workspace API文档
MCP协议规范
GitHub上的文件问题

状态： 生产就绪
版本： 0.2.0
最后更新时间： 2025-10-30