AI导哈

Google服务访问服务器

通过Model Context Protocol提供对Google服务（Gmail、Google Docs、Google Drive）的访问，支持OAuth 2.0和服务账户认证。

  • by Besjana-Kukaj
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 besjana-kukaj/google-mcp

使用说明

Google MCP服务器设置指南

概述

此MCP服务器通过模型上下文协议提供对谷歌服务（Gmail、谷歌文档、谷歌云端硬盘）的访问。它支持OAuth 2.0和服务帐户身份验证。

先决条件

  • Node.js 18或更高版本
  • TypeScript
  • 启用了所需API的谷歌云项目

安装说明

1.谷歌云控制台设置

  1. 首选 谷歌云控制台

  2. 创建新项目或选择现有项目

  3. 启用以下API：

    • Gmail API
    • 谷歌文档API
    • Google Drive API

  4. 创建OAuth 2.0凭据：

    • 转到“API和服务”>“凭据”
    • 点击“创建凭据”>“OAuth 2.0客户端ID”
    • 选择“桌面应用程序”
    • 下载JSON文件

2.环境配置

  1. 复制 .env.example 向 .env:

    cp .env.example .env

  2. 编辑 .env 并添加您的OAuth凭据：

    GOOGLE_CLIENT_ID=your_client_id_from_json
GOOGLE_CLIENT_SECRET=your_client_secret_from_json
GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback

3.构建和运行

  1. 安装依赖项：

    npm install

  2. 构建TypeScript代码：

    npm run build

  3. 运行服务器：

    npm start

身份验证流程

OAuth 2.0（建议个人使用）

  1. 使用 oauth_authenticate 获取授权URL的工具
  2. 访问URL并授权应用程序
  3. 从回调中复制授权码
  4. 使用 oauth_complete 带有授权码的工具
  5. 服务器将保存令牌并自动刷新它们

服务帐户（用于服务器部署）

  1. 在Google Cloud Console中创建服务帐户
  2. 下载服务帐户密钥JSON文件
  3. 设置 GOOGLE_APPLICATION_CREDENTIALS 文件路径的环境变量

可用工具

OAuth工具（使用OAuth 2.0时）

  • oauth_authenticate -启动OAuth流
  • oauth_complete -使用授权码完成OAuth
  • oauth_status -检查身份验证状态

Gmail工具

  • gmail_send_email -通过Gmail发送电子邮件
  • gmail_list_emails -列出最近的电子邮件

谷歌文档工具

  • docs_create_document -创建新文档
  • docs_read_document -读取文档内容
  • docs_update_document -更新文档内容（追加/替换）

谷歌云端硬盘工具

  • drive_list_files -列出驱动器中的文件

示例用法

  1. 首先，进行身份验证（OAuth 2.0）：

    {
  "tool": "oauth_authenticate"
}

  2. 使用代码完成身份验证：

    {
  "tool": "oauth_complete",
  "arguments": {
    "code": "your_authorization_code"
  }
}

  3. 发送电子邮件：

    {
  "tool": "gmail_send_email",
  "arguments": {
    "to": "recipient@example.com",
    "subject": "Test Email",
    "body": "Hello from MCP Server!"
  }
}

  4. 创建文档：

    {
  "tool": "docs_create_document",
  "arguments": {
    "title": "My New Document",
    "content": "This is the initial content."
  }
}

安全说明

  • OAuth令牌存储在 google-oauth-token.json 在项目根中
  • 令牌过期时会自动刷新
  • 永远不要承诺你的 .env 文件或令牌文件到版本控制
  • 为您的用例使用适当的范围

故障排除

  1. 身份验证错误：检查您的OAuth凭据是否正确，重定向URI是否匹配
  2. API错误：确保在您的项目中启用了所需的Google API
  3. 权限错误：确保用户在OAuth流程中授予了必要的权限
  4. 令牌刷新错误：删除 google-oauth-token.json 文件并重新验证

所需范围

服务器请求以下OAuth作用域：

  • https://www.googleapis.com/auth/documents -谷歌文档访问
  • https://www.googleapis.com/auth/drive.readonly -只读驱动器访问
  • https://www.googleapis.com/auth/drive.file -驱动器文件访问
  • https://www.googleapis.com/auth/gmail.send -发送电子邮件
  • https://www.googleapis.com/auth/gmail.readonly -阅读电子邮件 ..." } }

**Search for Unread Emails:**
```json
{
  "tool": "gmail_list_emails",
  "arguments": {
    "query": "is:unread",
    "maxResults": 5
  }
}

文档管理示例

创建会议笔记文档：

{
  "tool": "docs_create_document",
  "arguments": {
    "title": "Team Meeting Notes - December 2024",
    "content": "# Meeting Agenda\\n1. Project Status\\n2. Next Steps\\n3. Action Items"
  }
}

读取文档内容：

{
  "tool": "docs_read_document",
  "arguments": {
    "documentId": "1ABC123xyz..."
  }
}

文件附录：

{
  "tool": "docs_update_document",
  "arguments": {
    "documentId": "1ABC123xyz...",
    "content": "\\n\\n## Follow-up Items\\n- Review budget\\n- Schedule next meeting",
    "action": "append"
  }
}

驱动器文件管理

列出最近使用的文档：

{
  "tool": "drive_list_files",
  "arguments": {
    "query": "mimeType='application/vnd.google-apps.document'",
    "maxResults": 10
  }
}

搜索特定文件：

{
  "tool": "drive_list_files", 
  "arguments": {
    "query": "name contains 'budget' and modifiedTime > '2024-12-01T00:00:00'"
  }
}

故障排除

常见问题及解决方案

身份验证错误

问题： “需要身份验证”错误 解决：

  1. 检查OAuth令牌过期时间： oauth_status
  2. 重新验证： oauth_authenticate → oauth_complete
  3. 验证中的环境变量 .env
  4. 检查Google Cloud API权限

问题： 令牌刷新失败 解决：

  1. 删除 google-oauth-token.json 并重新验证
  2. 验证OAuth凭据是否正确
  3. 检查互联网连接
  4. 确保重定向URI与Google Cloud设置匹配

API权限错误

问题： “权限不足”或403错误 解决：

  1. 验证Google Cloud中是否启用了所需的API
  2. 检查OAuth范围是否包括必要的权限
  3. 对于服务帐户，确保IAM角色正确
  4. 通过服务帐户电子邮件共享资源

未找到文件/文档

问题： 找不到文档ID错误 解决：

  1. 验证文档ID是否正确（来自URL或驱动器API）
  2. 检查文档共享权限
  3. 确保文档未被删除
  4. 使用 drive_list_files 查找正确的文档ID

调试模式

通过设置启用详细日志记录：

NODE_ENV=development

日志文件

服务器日志输出到stderr，包括：

  • 身份验证状态
  • API请求详细信息
  • 带有堆栈跟踪的错误消息

OAuth回调服务器

要排除OAuth流的故障，请运行回调服务器：

npm run oauth-server

这将在以下位置启动本地服务器 http://localhost:3000 以处理OAuth重定向。

高级功能

资源端点

服务器为直接数据访问提供资源端点：

Gmail收件箱资源

URI: google://gmail/inbox
Description: Recent emails from Gmail inbox
MIME Type: application/json

最近使用的驱动器文件资源

URI: google://drive/recent
Description: Recently accessed Google Drive files
MIME Type: application/json

自定义Gmail查询

高级Gmail搜索运营商：

- has:attachment          # Emails with attachments
- larger:10M             # Emails larger than 10MB
- older_than:7d          # Emails older than 7 days
- in:sent               # Sent emails
- label:important       # Important emails
- from:me to:you        # Complex sender/recipient

文档文本提取

该服务器包括复杂的文本提取，可以处理：

  • 段落：常规文本内容
  • 表格：细胞含量提取
  • 格式化：保留基本结构
  • 富文本：转换为纯文本

自动令牌管理

服务器自动执行以下操作：

  • 刷新令牌：当访问令牌过期时
  • 保存令牌：将令牌持久化到磁盘
  • 处理错误：身份验证失败时性能下降
  • 验证范围：确保适当的权限

安全最佳实践

环境安全

  1. 永远不要泄露秘密

    .env
google-oauth-token.json
credentials.json

  2. 使用环境变量

    # Preferred: Environment variables
GOOGLE_ACCESS_TOKEN=...
GOOGLE_REFRESH_TOKEN=...

# Avoid: Hardcoded credentials

  3. 保护文件权限

    chmod 600 .env
chmod 600 google-oauth-token.json

OAuth安全

  1. 在生产环境中使用HTTPS

    GOOGLE_REDIRECT_URI=https://yourdomain.com/auth/callback

  2. 限制OAuth作用域

    • 仅请求必要的权限
    • 定期审核授权范围
    • 尽可能使用只读范围

  3. 代币轮换

    • 令牌自动刷新
    • 监控令牌过期
    • 实施适当的错误处理

服务帐户安全

  1. 最小特权原则

    • 授予最低要求的IAM角色
    • 使用特定的资源权限
    • 定期审核服务帐户访问权限

  2. 密钥管理

    • 定期轮换服务帐户密钥
    • 使用Google Cloud KMS进行密钥加密
    • 监控云审核日志中的密钥使用情况

网络安全

  1. 防火墙配置

    • 限制OAuth回调服务器访问
    • 为服务帐户使用内部网络
    • 监控API异常流量

  2. API使用监控

    • 设置配额监控
    • 启用审核日志记录
    • 监控异常访问模式

数据隐私

  1. 数据处理

    • 遵循数据保留政策
    • 实施适当的数据加密
    • 尊重用户隐私设置

  2. 合规

    • 遵守GDPR/CCPA要求
    • 实施数据访问控制
    • 维护审计跟踪

性能优化

请求优化

  1. 批量操作

    • 在可用时使用批处理API
    • 最小化单个API调用
    • 实现请求排队

  2. 缓存策略

    • 缓存文档元数据
    • 实施速率限制
    • 使用条件请求

错误处理

  1. 重试逻辑

    • 速率限制的指数回退
    • 暂时性错误的自动重试
    • 断路器型式

  2. 监控

    • 跟踪API使用配额
    • 监控响应时间
    • 设置故障警报

相关 MCP