AI导哈

Google日历任务管理服务

一个将Google日历和Google任务操作暴露为LLM工具的服务器，支持事件创建、更新、删除和任务管理功能。

  • by PabloSR06
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 PabloSR06/mcp-google-calendar

使用说明

mcp-google-calendar 翻译为中文是：“MCP（可能是指某种系统或平台）与谷歌日历”。不过，这里的“MCP”具体含义需要根据上下文来确定，因为“MCP”在不同领域可能有不同的含义。如果“MCP”是特定于某个系统或平台的缩写，那么翻译时可能需要保留该缩写或根据具体情况给出更准确的翻译。但基于提供的信息，上述翻译是一个较为通用的表述

一个Google日历和Google任务（MCP）服务器，用于将日历和任务操作作为工具暴露给大型语言模型（LLM）使用。

目录

重要：认证架构

此MCP服务器配置为使用单个Google帐户进行所有操作。 认证凭据（客户端ID、客户端密钥和刷新令牌）存储在环境变量中（.env 文件），这意味着此MCP服务器的所有用户都将与同一个Google日历和Google任务账户进行交互。

当前实施情况

  • 单账户模式一个Google帐户的凭据已在 .env 文件
  • 所有操作 （创建、读取、更新、删除事件和任务）操作都是在这个单一账户上进行的
  • 最适合于个人使用、单用户应用程序，或共享团队日历和任务列表

多用户场景

如果你需要 每个用户需使用自己的Google账户进行身份验证，此服务器需要进行修改：

  1. 添加用户认证层实现一个用户认证系统（OAuth2、会话、JWT等）
  2. 传递用户上下文修改MCP工具，使其使用经过身份验证的用户的令牌，而不是（之前的） .env 代币；标记；令牌
  3. 令牌刷新逻辑实现按用户刷新和管理令牌

注当前的实现版本更注重个人使用的简洁性。

设置

先决条件

  1. 一个谷歌账户
  2. 访问 Google Cloud Console
  3. 已安装 Node.js

逐步配置

1. 配置Google Cloud Console项目

  1. 首选 Google Cloud 控制台
  2. 创建一个新项目或选择一个现有项目
  3. 启用所需的API：
    • 谷歌日历API前往“APIs 和服务”>“库”，搜索“Google 日历 API”并点击“启用”
    • Google 任务 API转到“APIs和服务”>“库”，搜索“Google任务API”并点击“启用”

2. 创建OAuth 2.0凭据

  1. 前往“APIs和服务”>“凭据”
  2. 点击“创建凭据”> “OAuth 2.0 客户端ID”
  3. 如果是第一次使用，请配置OAuth同意屏幕：
    • 选择“外部”（如果您使用的是 Google Workspace，则选择“内部”）
    • 填写基本应用信息
    • 在“Scopes”中，不要添加任何范围（我们将通过编程方式来完成此操作）
    • 将您的电子邮件添加为测试用户
  4. 创建OAuth 2.0客户端ID：
    • 应用类型：“Web应用”
    • 名称：“Google 日历 MCP 服务器”
    • 授权重定向URI： http://localhost:8080/oauth/callback

3. 配置.env文件

  1. 从Google Cloud Console复制凭据
  2. 创建一个 .env 项目根目录下的文件：
# Google Cloud Console credentials
GOOGLE_CLIENT_ID=your_client_id_here.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your_client_secret_here

# This will be generated in the next step
GOOGLE_REFRESH_TOKEN=

# Default timezone for calendar operations
DEFAULT_TIMEZONE=Atlantic/Canary

4. 获取刷新令牌

运行安装脚本：

npm run setup:google

这个脚本将：

  1. 在端口8080上启动一个临时服务器
  2. 向您展示一个URL以授权该应用程序
  3. 在浏览器中打开该网址
  4. 授权后，给您一个 refresh_token
  5. 返回令牌 GOOGLE_REFRESH_TOKEN

5. 测试配置

npm run build
node dist/index.js

MCP客户端配置

将此添加到您的MCP客户端配置中（例如，Claude Desktop配置）：

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      //WIP: "args": ["mcp-google-calendar"],
      "env": {
        "GOOGLE_CLIENT_ID": "<your-client-id>",
        "GOOGLE_CLIENT_SECRET": "<your-client-secret>",
        "GOOGLE_REFRESH_TOKEN": "<your-refresh-token>",
        "DEFAULT_TIMEZONE": "Atlantic/Canary"
      }
    }
  }
}

使用方法

  1. 将TypeScript编译为JavaScript：
npm run build
  1. 运行MCP服务器：
node dist/index.js

使用MCP Inspector进行测试

你可以使用（以下工具/方法）来测试和调试这个MCP服务器 MCP Inspector（中文可译为）“MCP 检测器”或“MCP 监视器”，具体翻译取决于上下文和“MCP”在此处的具体含义。如果“MCP”是某个特定系统、设备或软件的缩写，那么翻译时可能需要考虑其专业背景来给出更准确的译名。但在此通用翻译中，“MCP Inspector”直译为“MCP 检测器”或“MCP 监视器”是较为常见的表达：

  1. 确保您已经构建了该项目：
npm run build
  1. 在（相应位置）设置你的环境变量 .env 文件：
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REFRESH_TOKEN=your-refresh-token
DEFAULT_TIMEZONE=Atlantic/Canary
  1. 更新 mcp-inspector-config.json 使用您的项目路径：
{
  "mcpServers": {
    "mcp-google-calendar": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "${GOOGLE_CLIENT_ID}",
        "GOOGLE_CLIENT_SECRET": "${GOOGLE_CLIENT_SECRET}",
        "GOOGLE_REFRESH_TOKEN": "${GOOGLE_REFRESH_TOKEN}",
        "DEFAULT_TIMEZONE": "${DEFAULT_TIMEZONE}"
      }
    }
  }
}
  1. 运行MCP检查器：
npx @modelcontextprotocol/inspector --config mcp-inspector-config.json
  1. 在浏览器中打开终端中显示的URL（默认应为http://localhost:6277），以通过Inspector用户界面与MCP服务器进行交互。

时区配置

这个MCP服务器支持灵活的时区配置：

  1. 默认时区设置 DEFAULT_TIMEZONE 在你的 .env 使用IANA时区格式保存文件（例如。， Atlantic/Canary， America/New_York， Asia/Tokyo)
  2. **每操作覆盖（或：每次操作重写）**在创建或更新事件时，您可以为该特定操作指定不同的时区
  3. 备用方案/回退方案如果未配置时区，服务器将默认为 Atlantic/Canary

时区优先级：

  1. 传递给工具的时区参数（最高优先级）
  2. DEFAULT_TIMEZONE 来自环境变量的 .env
  3. 硬编码默认值： Atlantic/Canary （最低优先级）

常见的IANA时区：

  • 欧洲： Atlantic/Canary， Europe/London， Europe/Paris， Europe/Berlin
  • 美洲： America/New_York， America/Chicago， America/Los_Angeles， America/Mexico_City
  • 亚洲： Asia/Tokyo， Asia/Shanghai， Asia/Dubai， Asia/Kolkata
  • 其他： Atlantic/Canary， Pacific/Auckland， Australia/Sydney

安全

  • 永远不要 分享你的 client_secret 或者 refresh_token
  • 添加 .env 到你的 .gitignore （已包含）
  • 令牌仅具有对Google日历和Google任务的有限权限

额外资源

可用工具

日历工具

创建日历事件

在Google日历中创建一个新的日历事件。

参数：

  • title字符串 - 事件标题/摘要
  • start日期时间字符串 - 事件开始时间（ISO 8601 格式）
  • end日期时间字符串 - 事件结束时间（ISO 8601 格式）
  • description字符串（可选）- 事件描述
  • location字符串（可选）- 事件地点
  • attendees电子邮件字符串数组（可选）- 参会者电子邮件地址列表
  • timeZone字符串（可选）- IANA 格式的时间区（例如，Atlantic/Canary，America/New_York）。默认为 DEFAULT_TIMEZONE 从 .env 文件或 'Atlantic/Canary'（时区）获取
  • calendarId字符串（可选）- 日历ID（默认为“primary”）

返回值：

  • 所创建事件的唯一标识符和详细信息

日历更新事件

更新Google日历中的现有事件。

参数：

  • eventId字符串 - 要更新的事件的唯一ID
  • title字符串（可选）- 新事件标题/摘要
  • start日期时间字符串（可选）- 新事件开始时间（ISO 8601 格式）
  • end日期时间字符串（可选）- 新事件结束时间（ISO 8601 格式）
  • description字符串（可选）- 新事件描述
  • location字符串（可选）- 新的活动地点
  • attendees电子邮件字符串数组（可选）- 参会者电子邮件地址列表
  • timeZone字符串（可选）- IANA 格式的时间区（例如，Atlantic/Canary，America/New_York）。默认为 DEFAULT_TIMEZONE 从 .env 文件或使用 'Atlantic/Canary'（时区）
  • calendarId字符串（可选）- 日历ID（默认为'primary'）

返回值：

  • 更新后的活动详情

日历列表事件

从Google日历中列出指定时间范围内的事件。

参数：

  • timeMin日期时间字符串（可选）- 时间段的开始（ISO 8601 格式）
  • timeMax日期时间字符串（可选）- 时间框架的结束时间（ISO 8601 格式）
  • calendarId字符串（可选）- 日历ID（默认为'primary'）
  • maxResults数量（可选）- 返回的最大事件数（默认：10）

返回值：

  • 在给定时间范围内发生的事件列表

日历搜索事件

在Google日历中通过文本查询搜索事件。

参数：

  • query字符串 - 搜索查询
  • calendarId字符串（可选）- 日历ID（默认为'primary'）
  • maxResults数量（可选）- 要返回的事件最大数量（默认：10）

返回值：

  • 符合搜索查询的活动列表

删除日历事件

从Google日历中删除一个事件。

参数：

  • eventId字符串 - 要删除的事件的唯一ID
  • calendarId字符串（可选）- 日历ID（默认为“primary”）

返回值：

  • 确认删除

日历列表-日历

列出用户可用的所有日历。

返回：

  • 包含日历ID和名称的日历列表

获取当前日期和时间的日历

获取ISO 8601格式的当前日期和时间。在创建或搜索事件时作为参考很有用。

参数：

  • timezone字符串（可选）- IANA 格式的时间区（例如，Atlantic/Canary，America/New_York，Asia/Tokyo）。默认值为 DEFAULT_TIMEZONE 从 .env 文件或设置为 'Atlantic/Canary'。

返回值：

  • 当前日期和时间信息，包括ISO 8601格式、时间戳、本地时间以及时区详情

任务工具

任务列表-任务列表（注：此句在中文语境下略显重复，通常可简化为“任务列表”或根据具体语境调整表达）

列出Google任务中所有可用的任务列表。

参数：无

返回值：

  • 所有任务列表及其ID和标题的清单

示例用例：

  • 获取你所有任务列表的清单，以找到 taskListId 用于创建或管理任务

任务列表-任务

列出特定任务列表中的所有任务。

参数：

  • taskListId字符串 - 任务列表的ID（使用 tasks-list-task-lists （为了得到这个）
  • showCompleted布尔值（可选）- 是否显示已完成的任务（默认：true）
  • maxResults数字（可选）- 要返回的最大任务数（默认：100）

返回值：

  • 包含任务详情（包括ID、标题、备注、状态、截止日期和完成日期）的任务列表

任务-创建任务

在Google任务中创建一个新任务。

参数：

  • taskListId字符串 - 将创建任务的任务列表的ID
  • title字符串 - 任务标题/摘要
  • notes字符串（可选）- 任务备注或描述
  • due日期时间字符串（可选）- 以ISO 8601格式表示的截止日期（例如，“2024-12-31T23:59:59Z”）

返回值：

  • 创建的任务详情包括ID、标题、备注、状态和截止日期

任务-更新任务

在Google任务中更新现有任务。

参数：

  • taskListId字符串 - 包含该任务的任务列表的ID
  • taskId字符串 - 要更新的任务的ID
  • title字符串（可选）- 新任务标题
  • notes字符串（可选）- 新任务的备注或描述
  • due日期时间字符串（可选）- 新截止日期，采用ISO 8601格式
  • status字符串（可选）- 任务状态：可以是“needsAction”（需要采取行动）或“completed”（已完成）

返回值：

  • 更新后的任务详情

任务-删除任务

从Google任务中删除任务。

参数：

  • taskListId字符串 - 包含该任务的任务列表的ID
  • taskId字符串 - 要删除的任务的ID

返回值：

  • 删除确认信息

许可证

麻省理工学院（MIT）

相关 MCP