Google 日历自动认证 MCP 服务器

这是一个用于 Claude 桌面版与 Google 日历集成的 Model Context Protocol (MCP) 服务器，支持自动认证。该服务器使 AI 助手能够通过自然语言交互来管理 Google 日历。


功能

• 创建带有标题、描述、地点和参与者的日历事件
• 更新现有的日历事件
• 删除日历事件
• 获取事件详情
• 列出指定时间范围内的事件
• 通过关键词搜索事件
• 列出所有可用的日历
• 支持自然语言日期/时间输入（例如，“明天下午2点”，“下周一”）
• 完全集成 Google 日历 API
• 简单的 OAuth2 认证流程，并自动启动浏览器
• 同时支持桌面应用和 Web 应用的凭证
• 全局凭证存储以方便使用

安装与认证

通过 Smithery 安装

要通过 Smithery 自动安装适用于 Claude 桌面版的 Google 日历集成服务器，请执行以下命令：

bash
npx -y @smithery/cli install @falgom4/calendar-mcp --client claude

手动安装

1. 创建一个 Google Cloud 项目并获取凭证：

   a. 创建 Google Cloud 项目：

   • 前往 Google Cloud 控制台
   • 创建新项目或选择现有项目
   • 为您的项目启用 Google 日历 API

   b. 创建 OAuth 2.0 凭证：

   • 转到 "APIs & Services" > "Credentials"
   • 点击 "Create Credentials" > "OAuth client ID"
   • 选择 "Desktop app" 或 "Web application" 作为应用程序类型
   • 给它命名并点击 "Create"
   • 对于 Web 应用程序，将 http://localhost:3000/oauth2callback 添加到授权重定向 URI 中
   • 下载客户端的 OAuth 密钥 JSON 文件
   • 将密钥文件重命名为 gcp-oauth.keys.json

2. 运行认证：

   您可以通过两种方式进行认证：

   a. 全局认证（推荐）:
   bash

   首次：将 gcp-oauth.keys.json 放在您主目录下的 .calendar-mcp 文件夹中

   mkdir -p ~/.calendar-mcp
   mv gcp-oauth.keys.json ~/.calendar-mcp/

   从任何地方运行认证

   npx @nchufa/calendar auth

   b. 本地认证:
   bash

   将 gcp-oauth.keys.json 放在当前目录中

   该文件将被自动复制到全局配置

   npx @nchufa/calendar auth

   认证过程将：

   • 在当前目录或 ~/.calendar-mcp/ 中查找 gcp-oauth.keys.json
   • 如果在当前目录找到，则将其复制到 ~/.calendar-mcp/
   • 打开默认浏览器进行 Google 认证
   • 将凭证保存为 ~/.calendar-mcp/credentials.json

   注意:

   • 成功认证后，凭证将全局存储在 ~/.calendar-mcp/ 中，可以从任何目录使用
   • 同时支持桌面应用和 Web 应用程序的凭证
   • 对于 Web 应用程序凭证，请确保将 http://localhost:3000/oauth2callback 添加到您的授权重定向 URI 中

3. 在 Claude 桌面版中配置：

将以下内容添加到您的 Claude 桌面版配置文件中：

json
{
"mcpServers": {
"calendar": {
"command": "npx",
"args": [
"@nchufa/calendar"
]
}
}
}

可用工具

服务器提供了以下可通过 Claude 桌面版使用的工具：

1. 创建事件 (create_event)

创建一个新的日历事件。

json
{
"summary": "团队会议",
"description": "每周团队同步讨论项目进展",
"location": "会议室 A",
"start": "2025-04-01T14:00:00",
"end": "2025-04-01T15:00:00",
"attendees": ["colleague@example.com", "manager@example.com"],
"reminders": {
"useDefault": false,
"overrides": [
{
"method": "email",
"minutes": 30
},
{
"method": "popup",
"minutes": 10
}
]
}
}自然语言日期/时间也受支持：

json
{
"summary": "与John喝咖啡",
"location": "市中心星巴克",
"start": "明天下午2:30",
"end": "明天下午3:30"
}

2. 获取事件 (get_event)

检索特定日历事件的详细信息。

json
{
"eventId": "abc123xyz456",
"calendarId": "primary"
}

3. 更新事件 (update_event)

更新现有的日历事件。

json
{
"eventId": "abc123xyz456",
"summary": "更新后的会议标题",
"location": "新地点",
"start": "2025-04-01T15:00:00",
"end": "2025-04-01T16:00:00"
}

4. 删除事件 (delete_event)

删除一个日历事件。

json
{
"eventId": "abc123xyz456",
"calendarId": "primary"
}

5. 列出事件 (list_events)

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

json
{
"calendarId": "primary",
"timeMin": "2025-04-01T00:00:00",
"timeMax": "2025-04-07T23:59:59",
"maxResults": 10,
"orderBy": "startTime"
}

6. 搜索事件 (search_events)

搜索与查询匹配的事件。

json
{
"query": "会议",
"calendarId": "primary",
"timeMin": "2025-04-01T00:00:00",
"maxResults": 5
}

7. 列出日历 (list_calendars)

列出所有可用的日历。

json
{}

自然语言日期/时间支持

服务器支持多种自然语言格式的日期和时间：

• 特定日期："2025-04-01T14:00:00"（ISO格式）
• 简单引用："今天"、"明天"、"现在"
• 相对时间："2小时后"、"3天后"
• 星期引用："下周一"、"下周二"
• 组合格式："明天下午2点"、"周一15:30"

这使得使用自然语言指令创建和更新事件变得非常容易。

安全注意事项

• OAuth凭据安全地存储在您的本地环境（~/.calendar-mcp/）中
• 服务器使用离线访问来保持持久认证
• 请勿共享或提交您的凭据到版本控制系统
• 定期审查并在Google帐户设置中撤销未使用的访问权限

故障排除

1. 找不到OAuth密钥

   • 确保gcp-oauth.keys.json位于当前目录或~/.calendar-mcp/中
   • 检查文件权限

2. 无效的凭据格式

   • 确保证书文件包含web或installed凭据
   • 对于Web应用程序，请验证重定向URI是否正确配置

3. 端口已被占用

   • 如果端口3000已被占用，请在运行身份验证之前释放该端口
   • 您可以找到并停止使用该端口的进程

贡献

欢迎贡献！请随时提交Pull Request。

许可证

MIT

致谢

特别感谢GongRzhe及其Calendar-Autoauth-MCP-Server项目，该项目为本实现奠定了基础。

支持

如果您遇到任何问题或有疑问，请在GitHub仓库上提交一个问题。