MCP 服务器

Google Calendar MCP Server

使大型语言模型（LLMs）能够通过标准化界面读取、创建和管理 Google 日历事件，包括列出日历、管理事件以及处理来自屏幕截图和图像的日历信息等功能。

README

Google Calendar MCP 服务器

这是一个模型上下文协议 (MCP) 服务器，提供与 Google Calendar 的集成。它允许 LLM 通过标准化接口读取、创建和管理日历事件。

功能

列出可用的日历
列出日历中的事件
创建新的日历事件
更新现有事件
删除事件
处理来自屏幕截图和图像的事件

要求

Node.js 16 或更高版本
TypeScript 5.3 或更高版本
启用了 Calendar API 的 Google Cloud 项目
OAuth 2.0 凭据（客户端 ID 和客户端密钥）

项目结构

google-calendar-mcp/
├── src/           # TypeScript 源代码文件
├── build/         # 编译后的 JavaScript 输出
├── llm/           # LLM 特定的配置和提示
├── package.json   # 项目依赖和脚本
└── tsconfig.json  # TypeScript 配置

Google Cloud 设置

转到 Google Cloud Console
创建一个新项目或选择一个现有项目。
为您的项目启用 Google Calendar API。在启用 API 之前，请确保从顶部栏中选择了正确的项目。
创建 OAuth 2.0 凭据：
- 转到凭据
- 点击“创建凭据”>“OAuth 客户端 ID”
- 为应用将访问的数据类型选择“用户数据”
- 添加您的应用名称和联系信息
- 添加以下范围（可选）：
  - https://www.googleapis.com/auth/calendar.events
- 选择“桌面应用”作为应用程序类型
- 在 OAuth 同意屏幕下添加您的电子邮件地址作为测试用户
  - 注意：添加测试用户需要几分钟时间。在测试用户传播之前，OAuth 同意将不允许您继续。

安装

克隆存储库
安装依赖项：
```
npm install
```
构建 TypeScript 代码：
```
npm run build
```
从 Google Cloud Console（在“凭据”下）下载您的 Google OAuth 凭据，并将文件重命名为 gcp-oauth.keys.json，并将其放置在项目的根目录中。

可用脚本

npm run build - 构建 TypeScript 代码
npm run build:watch - 在观察模式下构建 TypeScript 以进行开发
npm run dev - 使用 ts-node 在开发模式下启动服务器
npm run auth - 启动 Google OAuth 流程的身份验证服务器

身份验证

服务器支持自动和手动身份验证流程：

自动身份验证（推荐）

将您的 Google OAuth 凭据放在项目根目录中名为 gcp-oauth.keys.json 的文件中。
启动 MCP 服务器：
```
npm start
```
如果未找到有效的身份验证令牌，服务器将自动：
- 启动身份验证服务器（在端口 3000-3004 上）
- 打开一个浏览器窗口进行 OAuth 流程
- 安全地保存令牌（一旦通过身份验证）
- 关闭身份验证服务器
- 继续正常的 MCP 服务器操作

服务器会自动管理令牌刷新和重新身份验证（如果需要）：

令牌会在过期前自动刷新
如果刷新失败，清晰的错误消息会指导您完成重新身份验证
令牌文件以受限权限安全地存储

手动身份验证

对于高级用户或故障排除，您可以手动运行身份验证流程：

npm run auth

这将：

启动身份验证服务器
打开一个浏览器窗口进行 OAuth 流程
保存令牌并退出

安全注意事项

OAuth 凭据存储在 gcp-oauth.keys.json 中
身份验证令牌存储在具有 600 权限的 .gcp-saved-tokens.json 中
令牌会在后台自动刷新
每次 API 调用之前都会验证令牌完整性
身份验证服务器在成功身份验证后自动关闭
切勿将 OAuth 凭据或令牌文件提交到版本控制

用法

服务器公开以下工具：

list-calendars：列出所有可用的日历
list-events：列出日历中的事件
create-event：创建一个新的日历事件
update-event：更新一个现有的日历事件
delete-event：删除一个日历事件

与 Claude Desktop 一起使用

将此配置添加到您的 Claude Desktop 配置文件。例如：/Users/<user>/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "google-calendar": {
      "command": "node",
      "args": ["path/to/build/index.js"]
    }
  }
}

重启 Claude Desktop

使用示例

除了您期望的日历集成所具有的正常功能之外，您还可以做一些非常动态的事情，例如从屏幕截图和图像中添加事件等等。

从屏幕截图和图像中添加事件：
```
根据附加的屏幕截图将此事件添加到我的日历中。
```
支持的图像格式：PNG、JPEG、GIF 图像可以包含事件详细信息，例如日期、时间、地点和描述

检查出席情况：

明天哪些事件有尚未接受邀请的参与者？

自动协调事件：

这是我面试的人提供的一些可用时间。查看可用时间，并为我创建一个面试他们的事件，该事件在我的工作日历上是空闲的。

提供您自己的可用时间：

请查看我未来一周的个人和工作日历，提供可用时间。选择在东海岸正常工作时间内效果良好的时间。会议时间为 1 小时

开发

故障排除

常见问题和解决方案：

OAuth 令牌在一周（7 天）后过期
- 处于测试模式而不是生产模式的应用程序在一周后需要再次进行 OAuth 流程。
OAuth 令牌错误
- 确保您的 gcp-oauth.keys.json 格式正确
- 尝试删除 .gcp-saved-tokens.json 并重新进行身份验证
TypeScript 构建错误
- 确保已安装所有依赖项：npm install
- 检查您的 Node.js 版本是否符合先决条件
- 清除构建目录：rm -rf build/
图像处理问题
- 验证图像格式是否受支持
- 确保图像包含清晰、可读的文本