🚀 谷歌日历 MCP 服务器
本项目是一个使用 TypeScript 构建的 Model Context Protocol (MCP) 服务器，它集成了谷歌日历功能，能够帮助用户更便捷地管理谷歌日历。
🚀 快速开始
安装
npm install -g mcp-google-calendar
或直接运行：
npx -y mcp-google-calendar
先决条件
- Node.js（v16 或更高版本）
- 谷歌云平台账户
- 谷歌日历 API 已启用
- OAuth 2.0 凭证配置完成
配置
1. 谷歌云平台配置
- 访问 谷歌云控制台
- 创建新项目或选择现有项目
- 启用谷歌日历 API：
- 进入 "APIs & Services" > "Library"
- 搜索 "Google Calendar API"
- 点击 "Enable"
- 配置 OAuth 一致性界面：
- 访问 "APIs & Services" > "OAuth consent screen"
- 选择 "External" 用户类型（或 "Internal" 对于谷歌Workspace）
- 填写所需信息：
- 应用名称：mcp-calendar
- 用户支持邮箱：(你的邮箱)
- 开发者联系方式：(你的邮箱)
- 添加权限范围：
- 点击 "Add or Remove Scopes"
- 找到并选择 "https://www.googleapis.com/auth/calendar.events"
- 将你的邮箱添加为测试用户
- 完成设置流程
- 创建 OAuth 凭证：
- 进入 "Credentials" 部分
- 点击 "Create Credentials" > "OAuth Client ID"
- 选择应用类型为 "Desktop app"
- 命名（例如：MCP Calendar Desktop Client）
- 下载 JSON 文件并保存至项目目录下的
credentials.json
2. 环境配置
在项目根目录创建一个 .env 文件：
# 服务器配置
PORT=3420
# 谷歌日历 API 配置
CREDENTIALS_PATH=./credentials.json
启动服务器
使用标准 WebSocket 运行：
npx -y mcp-google-calendar
使用 Server-Sent Events (SSE) 运行：
npx -y mcp-google-calendar --sse
集成 Claude Desktop
在 claude_desktop_config.json 中添加如下配置：
{
"mcpServers": {
"mcp-google-calendar": {
"command": "npx",
"args": ["-y", "mcp-google-calendar"]
}
}
}
✨ 主要特性
- 无缝谷歌日历集成：支持 OAuth 2.0 认证，实现与谷歌日历的无缝对接。
- 持久化令牌存储：实现自动认证，无需用户频繁操作。
- 日历管理：可列出并操作日历及其事件，方便用户管理日历信息。
- 事件全生命周期操作：支持创建、读取、更新和删除日历事件，满足各种使用场景。
- 按日期范围获取事件：能够查询指定时间内的日历事件，提高信息检索效率。
- 实时更新推送：支持 Server-Sent Events (SSE) 传输协议，及时推送日历事件的更新。
- 简单集成：兼容 Claude 和其他 MCP 兼容的 AI 助手，便于与其他系统集成。
📦 安装指南
npm install -g mcp-google-calendar
或直接运行：
npx -y mcp-google-calendar
💻 使用示例
基础用法
启动服务器
使用标准 WebSocket 运行：
npx -y mcp-google-calendar
使用 Server-Sent Events (SSE) 运行：
npx -y mcp-google-calendar --sse
集成 Claude Desktop
在 claude_desktop_config.json 中添加如下配置：
{
"mcpServers": {
"mcp-google-calendar": {
"command": "npx",
"args": ["-y", "mcp-google-calendar"]
}
}
}
高级用法
日历创建
const calendar = await createCalendar({
summary: 'My New Calendar',
description: 'This is a new calendar created via API'
});
事件创建
const event = await createEvent({
calendarId: 'primary',
summary: 'Meeting with Team',
description: 'Discuss Q4 project plan',
start: {
timeZone: 'Asia/Shanghai',
dateTime: '2023-10-05T09:00:00'
},
end: {
timeZone: 'Asia/Shanghai',
dateTime: '2023-10-05T10:30:00'
}
});
📚 详细文档
功能模块
认证授权
- 获取授权码：通过 OAuth 2.0 获取访问令牌所需的授权码。
- 令牌刷新：实现令牌的自动刷新机制，确保长期有效访问。
日历管理
- 日历创建：可创建新的日历。
- 日历读取：获取指定日历的详细信息，包括名称、描述等。
- 日历更新：修改已存在的日历属性，例如更新日历名称或描述。
- 日历删除：移除不再需要的日历。
事件管理
- 事件创建：创建新的日历事件。
- 事件查询：
const events = await listEvents({
calendarId: 'primary',
timeMin: '2023-10-01T00:00:00',
timeMax: '2023-10-31T23:59:59'
});
- 事件更新：
const updatedEvent = await updateEvent({
calendarId: 'primary',
eventId: 'event_id_123',
summary: 'Updated Meeting'
});
- 事件删除：
await deleteEvent({
calendarId: 'primary',
eventId: 'event_id_123'
});
实时推送
通过 SSE 实现事件的实时更新通知，订阅特定日历的所有事件变更。
开发信息
项目结构
src/
├── index.ts # 入口文件
├── calendar.ts # 日历管理模块
├── event.ts # 事件管理模块
└── auth.ts # 认证授权模块
快速上手
- 安装依赖：
npm install @types/googleapis google-auth-library
- 初始化项目：
npx tsinit
- 编写代码并运行：
npm run dev
🔧 技术细节
本项目使用 TypeScript 构建，借助 Node.js 运行环境，通过 OAuth 2.0 认证与谷歌日历 API 进行交互。在代码结构上，将不同功能模块进行了分离，如认证授权模块、日历管理模块和事件管理模块，提高了代码的可维护性和可扩展性。同时，支持 WebSocket 和 Server-Sent Events (SSE) 两种通信协议，以满足不同的使用场景。
📄 安全注意事项
⚠️ 重要提示
- 确保
credentials.json文件的安全性，避免泄露敏感信息。- 严格限制 API 调用的权限范围，防止越权操作。
- 实时监控 API 请求和响应，及时发现异常行为。
- 针对不同的 API 错误码和异常情况，设计完善的容错机制。