STARWARCLOUD STARWAR.AI
返回市场
谷歌工作区-MCP

谷歌工作区-MCP

作者：craibo2 星标更新：2025-08-11
安装使用来源：spider==github.com

项目介绍

Google Workspace MCP Server

该项目是一个安全的MCP（模型-上下文-协议）服务器，作为大型语言模型（或其他代理）与Google Workspace服务之间的桥梁。它提供了一组工具，以只读方式与Google Drive、Gmail、Google Calendar和Google Tasks进行交互。

该服务器使用官方Python MCP SDK构建，并且可以与任何兼容MCP的主机一起使用，例如Claude for Desktop或Gemini CLI。

功能

  • Google Drive: 搜索文件，获取文件内容，并在多种文件类型中执行高级基于内容的搜索。
  • Gmail: 搜索电子邮件并获取邮件详情。
  • Google Calendar: 列出日历，搜索事件，并通过增强过滤器获取事件详情。
  • Google Tasks: 管理任务和子任务，支持全面的CRUD操作和搜索功能。
  • OAuth 2.0: 使用Google的OAuth 2.0流程进行安全认证。
  • Docker化: 准备使用Docker和Docker Compose进行部署。
  • 可配置: 支持通过环境变量设置默认日历ID和任务列表ID。

可用工具

此服务器向代理暴露以下工具：

Google Drive

  • search_drive(query: str): 在Google Drive中搜索与查询匹配的文件。
  • get_drive_file_details(file_id: str): 根据ID获取特定文件的元数据和内容。
  • search_drive_by_content(search_term: str, folder_id: Optional[str] = None, file_types: Optional[List[str]] = None, case_sensitive: bool = False, use_regex: bool = False, max_results: Optional[int] = None): 搜索包含特定文本内容的文件，具有高级选项。
  • search_within_file_content(file_id: str, search_term: str, case_sensitive: bool = False, use_regex: bool = False): 在单个文件内搜索特定内容。

Gmail

  • search_gmail(query: str, label_ids: Optional[List[str]] = None, max_results: int = 10): 在Gmail中搜索与查询匹配的电子邮件，可选地在特定标签内搜索。
  • get_gmail_message_details(message_id: str): 根据ID获取特定电子邮件消息的全部详情。
  • list_gmail_labels(): 列出所有可用的Gmail标签。
  • search_gmail_labels(query: str = ""): 搜索与查询匹配的Gmail标签。
  • get_gmail_label_details(label_id: str): 获取特定Gmail标签的详细信息。
  • search_gmail_by_label(label_id: str, query: str = "", max_results: int = 10): 在特定Gmail标签内搜索电子邮件。

Google Calendar

  • list_calendars(): 列出所有可用的日历。
  • list_calendar_events(calendar_ids: Optional[List[str]] = None, start_time: str, end_time: str, query: Optional[str] = None, max_results: int = 100): 列出指定日历在一段时间内的所有事件，具有可选过滤器。如果没有提供calendar_ids，则使用默认配置的日历。
  • search_calendar_events(calendar_ids: Optional[List[str]] = None, query: str, start_time: str, end_time: str): 搜索在指定时间段内与查询匹配的日历事件。如果没有提供calendar_ids，则使用默认配置的日历。
  • get_calendar_event_details(event_id: str, calendar_id: Optional[str] = None): 获取特定日历事件的全部详情。如果没有提供calendar_id，则使用第一个配置的默认日历。

Google Tasks

  • list_task_lists(): 列出所有可用的任务列表。
  • list_tasks(task_list_id: Optional[str] = None, max_results: int = 100): 列出特定任务列表中的所有任务。如果没有提供task_list_id，则使用默认配置的任务列表。
  • search_tasks(query: str, task_list_id: Optional[str] = None, max_results: int = 50): 根据查询文本搜索任务标题和描述中的任务。
  • search_tasks_by_period(start_date: str, end_date: str, task_list_id: Optional[str] = None, max_results: int = 50): 使用ISO 8601格式（YYYY-MM-DD）搜索特定日期范围内的任务。
  • create_task(title: str, task_list_id: Optional[str] = None, description: Optional[str] = None, due_date: Optional[str] = None, parent_task_id: Optional[str] = None): 创建新的任务或子任务，具有可选的描述、截止日期和父任务，用于分层结构。
  • update_task(task_id: str, task_list_id: Optional[str] = None, title: Optional[str] = None, description: Optional[str] = None, due_date: Optional[str] = None, status: Optional[str] = None): 更新现有任务属性，支持部分更新。
  • mark_task_completed(task_id: str, task_list_id: Optional[str] = None, completed: bool = True): 将任务标记为完成或未完成，自动设置完成时间戳。

内容搜索功能

Google Drive的内容搜索功能支持：

支持的文件类型

  • Google Docs（原生API支持）
  • PDF文件（文本提取）
  • 纯文本文件（TXT，CSV）
  • Microsoft Word文档（DOCX）

搜索选项

  • 大小写敏感/不敏感搜索
  • 正则表达式支持
  • 特定文件夹搜索范围
  • 文件类型过滤
  • 可配置的结果限制

搜索结果包括

  • 文件元数据（名称、ID、创建/修改日期、大小）
  • 包含突出显示匹配项的内容片段
  • 匹配计数和位置
  • 父文件夹信息

示例用法

Google Drive内容搜索

# 基本内容搜索
search_drive_by_content("项目需求")

# 大小写敏感搜索
search_drive_by_content("API", case_sensitive=True)

# 正则表达式搜索电子邮件模式
search_drive_by_content(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b", use_regex=True)

# 在特定文件夹内搜索
search_drive_by_content("预算", folder_id="folder123")

# 仅搜索特定文件类型
search_drive_by_content("报告", file_types=["application/pdf", "application/vnd.google-apps.document"])

# 在特定文件内搜索
search_within_file_content("file_id_123", "特定术语")

Gmail标签管理

# 列出所有标签
list_gmail_labels()

# 搜索包含“工作”的标签
search_gmail_labels("工作")

# 获取特定标签的详细信息
get_gmail_label_details("Label_123")

Google任务管理

# 列出所有可用的任务列表
list_task_lists()

# 列出默认任务列表中的任务
list_tasks()

# 搜索包含“会议”的任务
search_tasks("会议")

# 搜索特定期间到期的任务
search_tasks_by_period("2024-01-01", "2024-01-31")

# 创建新任务
create_task("审查项目提案", description="审查第一季度项目提案文档")

# 创建子任务
create_task("准备演示", parent_task_id="task123", due_date="2024-01-15")

# 更新任务描述
update_task("task123", description="更新项目提案审查，添加新要求")

# 标记任务为已完成
mark_task_completed("task123", completed=True)

先决条件

  • Python 3.10+
  • Docker 和 Docker Compose（用于容器化部署）
  • 启用了必要API的Google Cloud项目。

设置和配置

  1. Google Cloud凭证：

    步骤1：创建Google Cloud项目

    • 转到Google Cloud控制台。
    • 单击页面顶部的项目下拉菜单并选择“新建项目”。
    • 输入项目名称（例如，“google-workspace-mcp”），然后点击“创建”。
    • 等待项目创建完毕，然后从项目下拉菜单中选择它。

    步骤2：启用所需API

    • 在您的新项目中，导航至“API和服务”>“库”。
    • 搜索并依次启用以下API：
      • Google Drive API - 搜索“Google Drive API”并点击“启用”
      • Gmail API - 搜索“Gmail API”并点击“启用”
      • Google Calendar API - 搜索“Google Calendar API”并点击“启用”
      • Google Tasks API - 搜索“Tasks API”并点击“启用”

    步骤3：配置OAuth同意屏幕

    • 导航至“API和服务”>“OAuth同意屏幕”。
    • 选择外部并点击“创建”。
    • 填写所需字段：
      • 应用名称：Google Workspace MCP Server
      • 用户支持邮箱：您的邮箱地址
      • 开发者联系信息：您的邮箱地址
    • 点击“保存并继续”。
    • 在“范围”页面上，点击“添加或移除范围”。
    • 查找并添加以下范围：
      • https://www.googleapis.com/auth/drive.readonly（查看Google Drive中的文件）
      • https://www.googleapis.com/auth/gmail.readonly（阅读所有资源及其元数据）
      • https://www.googleapis.com/auth/calendar.readonly（查看您所有日历上的事件）
      • https://www.googleapis.com/auth/tasks（管理您的任务）
    • 点击“更新”，然后“保存并继续”。
    • 在“测试用户”页面上，点击“+ 添加用户”。
    • 添加您的Google账户邮箱地址（您将访问的Drive、Gmail和日历的账户）。
    • 点击“保存并继续”。

    步骤4：创建OAuth 2.0凭证

    • 导航至“API和服务”>“凭证”。
    • 点击“+ 创建凭证”>“OAuth客户端ID”。
    • 对于应用类型，选择桌面应用。
    • 给它一个名字，如“Google Workspace MCP Server”。
    • 点击“创建”。
    • 弹出窗口会显示您的客户端ID和客户端密钥。点击下载JSON。
    • 将下载的文件重命名为credentials.json并保存在项目的根目录中。
    • 重要：此文件包含敏感信息，不应公开分享或提交到版本控制系统。

  2. 本地环境（开发用途）：

    • 高度建议使用虚拟环境来管理项目依赖。 
      python3 -m venv .venv
    • 安装所需的Python包： 
      ./.venv/bin/pip install -r requirements.txt

配置选项

默认日历ID

您可以配置默认日历ID，当没有提供特定日历时将使用这些ID。这对于设置常用日历非常有用。

环境变量：DEFAULT_CALENDAR_IDS

示例：

export DEFAULT_CALENDAR_IDS="primary,work@公司.com,personal@gmail.com"

内容搜索配置

您可以使用环境变量配置内容搜索行为：

环境变量：

  • MAX_CONTENT_SEARCH_RESULTS: 搜索结果的最大数量（默认：50）
  • CONTENT_SEARCH_SNIPPET_LENGTH: 搜索结果片段的字符长度（默认：200）

示例：

export MAX_CONTENT_SEARCH_RESULTS=100
export CONTENT_SEARCH_SNIPPET_LENGTH=300

Google任务配置

您可以使用环境变量配置Google任务的行为：

环境变量：

  • DEFAULT_TASK_LIST_ID: 默认任务列表ID（默认：'@default'）
  • MAX_TASK_SEARCH_RESULTS: 任务搜索结果的最大数量（默认：1[END_OF_TEXT]