Google Calendar MCP Server

🚀 Google Calendar MCP Server

Google Calendar MCP Server 是一个基于模型上下文协议（MCP）的服务器，它具备全面的 Google Calendar 集成能力。该服务器允许 AI 助手和应用程序通过标准化协议与 Google Calendar 进行交互。

🚀 快速开始

运行服务器

# 启动编译后的服务器
npm start

# 或者在开发模式下运行
npm run dev

与 MCP 客户端集成

将此服务器添加到您的 MCP 客户端配置中：

{
  "servers": {
    "google-calendar": {
      "type": "stdio",
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}

对于使用 MCP 扩展的 VS Code，将以下内容添加到 .vscode/mcp.json 中：

{
  "servers": {
    "google-calendar-mcp-server": {
      "type": "stdio",
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}

认证设置

1. 创建服务账户：
   • 访问 Google Cloud Console。
   • 导航到“IAM & Admin”>“服务账户”。
   • 创建一个新的服务账户。
   • 下载 JSON 密钥文件。
2. 共享日历访问权限：
   • 打开 Google Calendar。
   • 进入日历设置。
   • 与服务账户的电子邮件共享您的日历。
   • 授予“对活动进行更改”的权限。
3. 配置环境：
   • 将 JSON 密钥文件放在您的项目目录中。
   • 使用正确的路径更新 .env 文件。

✨ 主要特性

• 列出活动：从 Google Calendar 检索活动，并支持过滤选项。
• 创建活动：可完全自定义地创建新的日历活动。
• 更新活动：修改现有的日历活动。
• 删除活动：从日历中移除活动。
• 列出日历：获取经过身份验证的用户可用的日历。
• OAuth 认证：安全地访问 Google Calendar API。

📦 安装指南

前提条件

1. Google Cloud 项目：在 Google Cloud Console 中创建一个项目。
2. 启用 Google Calendar API：为您的项目启用日历 API。
3. 服务账户：创建一个服务账户并下载 JSON 密钥文件。

安装步骤

1. 克隆此仓库。
2. 安装依赖项：

   npm install
   

3. 复制环境文件并进行配置：

   copy .env.example .env
   

4. 编辑 .env 文件，设置您的 Google 服务账户密钥文件路径：

   GOOGLE_SERVICE_ACCOUNT_KEY_FILE=./path/to/your/service-account-key.json
   

构建项目

# 构建 TypeScript 代码
npm run build

# 开发模式，支持热重载
npm run dev

# 类型检查
npm run type-check

# 清理构建产物
npm run clean

💻 使用示例

list_events

使用各种过滤选项从 Google Calendar 检索活动。

参数：

• calendarId（可选）：日历 ID（默认值："primary"）
• timeMin（可选）：活动开始时间的下限（RFC3339 时间戳）
• timeMax（可选）：活动开始时间的上限（RFC3339 时间戳）
• maxResults（可选）：活动的最大数量（默认值：250）
• singleEvents（可选）：展开重复活动（默认值：true）
• orderBy（可选）：按“startTime”或“updated”对活动进行排序

create_event

在 Google Calendar 中创建一个新的活动。

参数：

• calendarId（可选）：日历 ID（默认值："primary"）
• summary（必需）：活动标题
• description（可选）：活动描述
• start（必需）：包含 dateTime 和可选 timeZone 的开始日期/时间对象
• end（必需）：包含 dateTime 和可选 timeZone 的结束日期/时间对象
• location（可选）：活动地点
• attendees（可选）：包含电子邮件和显示名称的参与者对象数组
• recurrence（可选）：用于重复活动的 RRULE 字符串数组

update_event

更新现有的日历活动。

参数：

• calendarId（可选）：日历 ID（默认值："primary"）
• eventId（必需）：要更新的活动 ID
• summary（可选）：新的活动标题
• description（可选）：新的活动描述
• start（可选）：新的开始日期/时间
• end（可选）：新的结束日期/时间
• location（可选）：新的活动地点
• attendees（可选）：新的参与者列表

delete_event

从 Google Calendar 中删除一个活动。

参数：

• calendarId（可选）：日历 ID（默认值："primary"）
• eventId（必需）：要删除的活动 ID

list_calendars

列出经过身份验证的用户可用的 Google 日历。

参数：

• minAccessRole（可选）：最小访问角色过滤器
• showDeleted（可选）：包括已删除的日历（默认值：false）
• showHidden（可选）：包括隐藏的日历（默认值：false）

📚 详细文档

项目结构

src/
├── index.ts          # 主要的 MCP 服务器实现
├── types/            # TypeScript 类型定义
└── utils/            # 实用函数

.env.example          # 环境变量模板
tsconfig.json         # TypeScript 配置
package.json          # Node.js 依赖项和脚本

添加新工具

1. 定义一个 Zod 模式用于输入验证。
2. 创建一个 ToolSchema 定义。
3. 实现异步处理函数。
4. 在服务器中注册该工具。
5. 添加全面的错误处理。

错误处理

所有工具都返回结构化响应：

// 成功响应
{
  content: [{ type: "text", text: JSON.stringify(result) }]
}

// 错误响应
{
  content: [{ type: "text", text: JSON.stringify(error) }],
  isError: true
}

🔧 技术细节

安全注意事项

• 切勿将服务账户密钥提交到版本控制中。
• 对所有敏感配置使用环境变量。
• 实施适当的错误处理，避免信息泄露。
• 定期轮换服务账户密钥。
• 遵循 Google Cloud 的安全最佳实践。

贡献指南

1. 分叉此仓库。
2. 创建一个功能分支。
3. 进行更改并进行适当的测试。
4. 提交拉取请求。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

支持

如有问题和疑问：

• 查看 Google Calendar API 文档。
• 查看 MCP 规范。
• 在本仓库中创建一个问题。