使用说明

谷歌工作区MCP服务器

该项目是一个安全的MCP（模型上下文协议）服务器，充当大型语言模型（或任何其他代理）和Google Workspace服务之间的桥梁。它公开了一组以只读方式与Google云端硬盘、Gmail、Google日历和Google任务交互的工具。

此服务器是使用官方 Python MCP SDK 并且已准备好与任何MCP兼容的主机一起使用，例如Claude for Desktop或 Gemini CLI.

特性

Google 云端硬盘：搜索文件、检索文件内容，并跨多种文件类型执行高级基于内容的搜索。
Gmail：搜索电子邮件并获取电子邮件详细信息。
谷歌日历：使用增强的过滤功能列出日历、搜索事件并获取事件详细信息。
工作表：通过全面的CRUD操作和搜索功能管理任务和子任务。
OAuth 2.0：使用Google的OAuth 2.0流进行安全身份验证。
Docker化：已准备好使用Docker和Docker Compose进行部署。
可配置的：通过环境变量支持默认日历ID和任务列表ID。

可用工具

此服务器向代理公开以下工具：

Google 云端硬盘

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标签内的电子邮件。

谷歌日历

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_id，则使用默认配置的日历。
search_calendar_events(calendar_ids: Optional[List[str]] = None, query: str, start_time: str, end_time: str)：搜索指定时间范围内与查询匹配的日历事件。如果没有提供calendar_id，则使用默认配置的日历。
get_calendar_event_details(event_id: str, calendar_id: Optional[str] = None)：获取特定日历事件的完整详细信息。如果没有提供calendar_id，则使用第一个配置的默认日历。

工作表

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内容搜索功能支持：

支持的文件类型

谷歌文件 （本机API支持）
PDF文件 （文本提取）
纯文本文件 （TXT、CSV）
Microsoft Word文档 （DOCX）

搜索选项

区分大小写/不区分大小写的搜索
正则表达式支持
文件夹特定搜索范围
文件类型筛选
可配置的结果限制

搜索结果包括

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

示例用法

谷歌云端硬盘内容搜索

# Basic content search
search_drive_by_content("project requirements")

# Case-sensitive search
search_drive_by_content("API", case_sensitive=True)

# Regex search for email patterns
search_drive_by_content(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b", use_regex=True)

# Search within specific folder
search_drive_by_content("budget", folder_id="folder123")

# Search specific file types only
search_drive_by_content("report", file_types=["application/pdf", "application/vnd.google-apps.document"])

# Search within a specific file
search_within_file_content("file_id_123", "specific term")

Gmail标签管理

# List all labels
list_gmail_labels()

# Search for labels containing "work"
search_gmail_labels("work")

# Get details for a specific label
get_gmail_label_details("Label_123")

谷歌任务管理

# List all available task lists
list_task_lists()

# List tasks from default task list
list_tasks()

# Search for tasks containing "meeting"
search_tasks("meeting")

# Search for tasks due in a specific period
search_tasks_by_period("2024-01-01", "2024-01-31")

# Create a new task
create_task("Review project proposal", description="Review the Q1 project proposal document")

# Create a sub-task
create_task("Prepare presentation", parent_task_id="task123", due_date="2024-01-15")

# Update task description
update_task("task123", description="Updated project proposal review with new requirements")

# Mark task as completed
mark_task_completed("task123", completed=True)

先决条件

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

设置和配置

谷歌云凭据:

第一步：创建谷歌云项目
- 转到谷歌云控制台.
- 单击页面顶部的项目下拉列表，然后选择“新建项目”。
- 输入项目名称（例如“谷歌工作区mcp”），然后单击“创建”。
- 等待项目创建，然后从项目下拉列表中选择它。
步骤2：启用所需的API
- 在您的新项目中，导航到“API和服务”>“库”。
- 逐一搜索并启用以下API：
  - Google Drive API -搜索“Google Drive API”并单击“启用”
  - Gmail API -搜索“Gmail API”并单击“启用”
  - 谷歌日历API -搜索“Google Calendar API”并单击“启用”
  - 谷歌任务API -搜索“任务API”并单击“启用”
步骤3：配置OAuth同意屏幕
- 导航到“API和服务”>“OAuth同意屏幕”。
- 选择外部然后单击“创建”。
- 填写必填字段：
  - 应用程序名称：谷歌工作区MCP服务器
  - 用户支持电子邮件：您的电子邮件地址
  - 开发人员联系信息：您的电子邮件地址
- 单击“保存并继续”。
- 在“范围”页面上，单击“添加或删除范围”。
- 查找并添加以下范围：
  - 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帐户电子邮件地址（您将访问其云端硬盘、Gmail和日历的帐户）。
- 单击“保存并继续”。
步骤4：创建OAuth 2.0凭据
- 导航到“API和服务”>“凭据”。
- 单击“+创建证书”>“OAuth客户端ID”。
- 对于 应用程序类型，选择 桌面应用程序.
- 给它起个名字，比如“谷歌工作区MCP服务器”。
- 单击“创建”。
- 将出现一个弹出窗口，其中包含您的客户端ID和客户端密码。点击 下载JSON.
- 将下载的文件重命名为 credentials.json 并将其保存在此项目的根目录中。
- 重要：此文件包含敏感信息，不应公开共享或提交版本控制。
当地环境（促进发展）:
- 强烈建议使用虚拟环境来管理项目依赖关系。
```
python3 -m venv .venv
```
- 安装所需的Python包：
```
./.venv/bin/pip install -r requirements.txt
```

配置选项

默认日历ID

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

环境变量: DEFAULT_CALENDAR_IDS

示例:

export DEFAULT_CALENDAR_IDS="primary,work@company.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：任务搜索结果的最大数量（默认值：100）
DEFAULT_TASK_MAX_RESULTS：列出时返回的默认最大任务数（默认值：100）

示例:

export DEFAULT_TASK_LIST_ID="@default"
export MAX_TASK_SEARCH_RESULTS=200
export DEFAULT_TASK_MAX_RESULTS=150

在MCP客户端配置中:

{
  "mcpServers": {
    "google-workspace": {
      "command": "/path/to/python",
      "args": ["server.py"],
      "workingDirectory": "/path/to/project",
      "env": {
        "DEFAULT_CALENDAR_IDS": "primary,work@company.com",
        "MAX_CONTENT_SEARCH_RESULTS": "100",
        "CONTENT_SEARCH_SNIPPET_LENGTH": "300"
      }
    }
  }
}

运行服务器

服务器通过以下方式进行通信 stdio，这是MCP服务器的标准配置。为了使MCP客户端正确连接，服务器应直接在主机系统上运行。

本地运行（建议用于MCP客户端）

启动服务器: 您第一次运行该应用程序时，它将打开一个浏览器窗口，让您授权访问您的谷歌帐户。
```
./.venv/bin/python server.py
```
成功授权后，a token.json 文件将在根目录中创建，以存储您的OAuth令牌。

使用Docker运行（替代方案）

Docker主要用于将应用程序容器化的部署场景。但是，对于MCP客户端集成，建议在本地运行。

构建并启动容器:
```
docker-compose up --build
```
这 docker-compose.yml 配置确保 credentials.json 文件对容器可用，并且 token.json 文件保存在Docker卷中。

连接到MCP服务器

此服务器设计为与MCP主机一起使用，例如Claude for Desktop或 Gemini CLI为了正确的工具发现和通信，服务器应直接在主机系统上运行。

MCP客户端配置示例

例如，要将此服务器连接到Claude For Desktop或Gemini CLI，您需要将以下内容添加到配置文件中。请咨询官方 MCP文件有关此文件在系统上的位置。

本地服务器配置（推荐）

{
  "mcpServers": {
    "google-workspace": {
      "command": "/ABSOLUTE/PATH/TO/google-workspace-mcp/.venv/bin/python",
      "args": [
        "server.py"
      ],
      "workingDirectory": "/ABSOLUTE/PATH/TO/google-workspace-mcp",
      "env": {
        "DEFAULT_CALENDAR_IDS": "primary,work@company.com",
        "DEFAULT_TASK_LIST_ID": "@default",
        "MAX_TASK_SEARCH_RESULTS": "100",
        "DEFAULT_TASK_MAX_RESULTS": "100"
      }
    }
  }
}

重要配置说明:

命令：必须指向Python可执行文件内部虚拟环境(.venv/bin/python)
工作目录：必须是项目根目录的绝对路径，其中 server.py 和 credentials.json 位于
参数：用途 server.py （不是完整路径），因为工作目录设置正确

对于您的系统：以上路径适用于您当前的设置。如果移动项目，请同时更新 command 和 workingDirectory 相应的路径。

Gemini CLI配置

使用此服务器 Gemini CLI，您可以在Gemini CLI设置中配置它：

{
  "mcpServers": {
    "google-workspace": {
      "command": "/ABSOLUTE/PATH/TO/google-workspace-mcp/.venv/bin/python",
      "args": ["server.py"],
      "workingDirectory": "/ABSOLUTE/PATH/TO/google-workspace-mcp",
      "env": {
        "DEFAULT_CALENDAR_IDS": "primary,work@company.com",
        "DEFAULT_TASK_LIST_ID": "@default",
        "MAX_TASK_SEARCH_RESULTS": "100",
        "DEFAULT_TASK_MAX_RESULTS": "100"
      }
    }
  }
}

Docker服务器配置

如果你更喜欢在Docker中运行服务器，你可以使用以下配置：

{
  "mcpServers": {
    "google-workspace": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/ABSOLUTE/PATH/TO/google-workspace-mcp:/app",
        "-w",
        "/app",
        "google-workspace-mcp:latest",
        "python",
        "server.py"
      ],
      "env": {
        "DEFAULT_CALENDAR_IDS": "primary,work@company.com",
        "DEFAULT_TASK_LIST_ID": "@default",
        "MAX_TASK_SEARCH_RESULTS": "100",
        "DEFAULT_TASK_MAX_RESULTS": "100"
      }
    }
  }
}

Docker配置的先决条件：

构建Docker镜像:

docker build -t google-workspace-mcp:latest .

确保credentials.json位于项目根目录中:

# Make sure credentials.json is in the project directory
ls -la credentials.json

替换卷路径：更新 /ABSOLUTE/PATH/TO/google-workspace-mcp 根据您的实际项目路径。

Docker配置说明：

这 -i 标志使STDIN保持打开状态，以便MCP通信
这 -v 标志将项目目录装载到 /app 在集装箱内
这 -w /app 在容器中设置工作目录
这 --rm 标志在容器停止后将其移除
环境变量通过 env 章节

故障排除

常见问题

1.“没有名为'mcp'的模块”错误

问题：服务器找不到MCP模块或其他依赖项。

解决方案：确保您在虚拟环境中使用Python可执行文件：

# Correct way to run the server
.venv/bin/python server.py

# Or activate the virtual environment first
source .venv/bin/activate
python server.py

MCP配置修复：确保 command 指向虚拟环境Python：

{
  "command": "/ABSOLUTE/PATH/TO/google-workspace-mcp/.venv/bin/python"
}

2.server.py或credentials.json的“找不到文件”错误

问题：MCP客户端找不到所需的文件。

解决方案：确保 workingDirectory 设置为项目根：

{
  "workingDirectory": "/ABSOLUTE/PATH/TO/google-workspace-mcp"
}

3.OAuth身份验证问题

问题：服务器无法通过Google API进行身份验证。

解决方案:

确保 credentials.json 存在于项目根目录中

手动运行身份验证流程：

.venv/bin/python -c "from src.auth import get_credentials; get_credentials()"

验证 token.json 已创建

4.服务器挂起或不响应

问题：服务器已启动，但未与MCP客户端通信。

解决方案：这是正常行为！服务器等待来自MCP客户端的stdio输入。服务器应：

启动成功（您将在日志中看到“正在启动MCP服务器…”）
等待输入（无错误消息）
MCP客户端发送请求时响应

测试配置

要测试您的MCP配置是否正确：

测试Python可执行文件:

/ABSOLUTE/PATH/TO/google-workspace-mcp/.venv/bin/python -c "import mcp; print('✅ MCP module found')"

测试服务器启动:
```
/ABSOLUTE/PATH/TO/google-workspace-mcp/.venv/bin/python /ABSOLUTE/PATH/TO/google-workspace-mcp/server.py
```
您应该看到“正在启动MCP服务器…”，然后进程应该等待输入。

测试文件可访问性:

ls -la /ABSOLUTE/PATH/TO/google-workspace-mcp/server.py
ls -la /ABSOLUTE/PATH/TO/google-workspace-mcp/credentials.json

Google Workspace集成服务

使用说明

谷歌工作区MCP服务器

特性

可用工具

Google 云端硬盘

Gmail

谷歌日历

工作表

内容搜索功能

支持的文件类型

搜索选项

搜索结果包括

示例用法

谷歌云端硬盘内容搜索

Gmail标签管理

谷歌任务管理

先决条件

设置和配置

配置选项

默认日历ID

内容搜索配置

Google任务配置

运行服务器

本地运行（建议用于MCP客户端）

使用Docker运行（替代方案）

连接到MCP服务器

MCP客户端配置示例

本地服务器配置（推荐）

Gemini CLI配置

Docker服务器配置

故障排除

常见问题

1.“没有名为'mcp'的模块”错误

2.server.py或credentials.json的“找不到文件”错误

3.OAuth身份验证问题

4.服务器挂起或不响应

测试配置

连接至`

使用说明

谷歌工作区MCP服务器

特性

可用工具

Google 云端硬盘

Gmail

谷歌日历

工作表

内容搜索功能

支持的文件类型

搜索选项

搜索结果包括

示例用法

谷歌云端硬盘内容搜索

Gmail标签管理

谷歌任务管理

先决条件

设置和配置

配置选项

默认日历ID

内容搜索配置

Google任务配置

运行服务器

本地运行（建议用于MCP客户端）

使用Docker运行（替代方案）

连接到MCP服务器

MCP客户端配置示例

本地服务器配置（推荐）

Gemini CLI配置

Docker服务器配置

故障排除

常见问题

1.“没有名为'mcp'的模块”错误

2.server.py或credentials.json的“找不到文件”错误

3.OAuth身份验证问题

4.服务器挂起或不响应

测试配置

连接至`

相关 MCP

AKShare One MCP 股市数据服务

实时网络搜索服务

arXiv 论文检索 MCP 服务器

移动自动化MCP服务器

AI持久记忆服务器

Git仓库管理MCP服务器