日历-mcp

Name: 日历-mcp
Author: falgom4

作者：falgom42 星标更新：2025-05-17

安装使用来源：spider==github.com

项目介绍

Google Calendar AutoAuth MCP Server

这是一个用于在 Claude Desktop 中集成 Google Calendar 并支持自动认证的 Model Context Protocol (MCP) 服务器。该服务器使AI助手能够通过自然语言交互来管理 Google Calendar。

功能

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

安装与认证

通过 Smithery 安装

要通过 Smithery 自动安装 Google Calendar 集成服务器到 Claude Desktop：

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

手动安装

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

a. 创建一个 Google Cloud 项目：
- 转到 Google Cloud 控制台
- 创建一个新的项目或选择一个现有项目
- 为您的项目启用 Google Calendar API
b. 创建 OAuth 2.0 凭证：
- 转到 "APIs & Services" > "Credentials"
- 点击 "Create Credentials" > "OAuth client ID"
- 选择 "Desktop app" 或 "Web application" 作为应用类型
- 给它命名并点击 "Create"
- 对于 Web 应用程序，请在授权重定向 URI 中添加 http://localhost:3000/oauth2callback
- 下载客户端的 OAuth 密钥 JSON 文件
- 将密钥文件重命名为 gcp-oauth.keys.json
运行认证：

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

a. 全局认证（推荐）：
```
# 第一次：将 gcp-oauth.keys.json 放入您家目录的 .calendar-mcp 文件夹中
mkdir -p ~/.calendar-mcp
mv gcp-oauth.keys.json ~/.calendar-mcp/

# 从任何地方运行认证
npx @nchufa/calendar auth
```
b. 局部认证：
```
# 将 gcp-oauth.keys.json 放入当前目录
# 文件将被自动复制到全局配置
npx @nchufa/calendar auth
```
认证过程会：
- 在当前目录或 ~/.calendar-mcp/ 查找 gcp-oauth.keys.json
- 如果在当前目录找到，则将其复制到 ~/.calendar-mcp/
- 使用默认浏览器进行 Google 认证
- 将凭证保存为 ~/.calendar-mcp/credentials.json
注意：
- 成功认证后，凭证将全局存储在 ~/.calendar-mcp/ 中，并可以从任何目录使用
- 同时支持桌面应用和网络应用凭证
- 对于网络应用凭证，请确保在授权重定向 URI 中添加 http://localhost:3000/oauth2callback
在 Claude Desktop 中配置：

向您的 Claude Desktop 配置文件添加以下内容：

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

可用工具

该服务器提供了以下工具，可通过 Claude Desktop 使用：

1. 创建事件 (`create_event`)

创建新的日历事件。

{
  "summary": "团队会议",
  "description": "每周团队同步讨论项目进度",
  "location": "会议室A",
  "start": "2025-04-01T14:00:00",
  "end": "2025-04-01T15:00:00",
  "attendees": ["同事@example.com", "经理@example.com"],
  "reminders": {
    "useDefault": false,
    "overrides": [
      {
        "method": "email",
        "minutes": 30
      },
      {
        "method": "popup",
        "minutes": 10
      }
    ]
  }
}

也支持自然语言日期/时间：

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

2. 获取事件 (`get_event`)

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

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

3. 更新事件 (`update_event`)

更新现有的日历事件。

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

4. 删除事件 (`delete_event`)

删除日历事件。

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

5. 列出事件 (`list_events`)

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

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

6. 搜索事件 (`search_events`)

按查询搜索匹配的事件。

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

7. 列出日历 (`list_calendars`)

列出所有可用的日历。

{}

自然语言日期/时间支持

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

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

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

安全注意事项

OAuth 凭证安全地存储在本地环境 (~/.calendar-mcp/)
服务器使用离线访问来维持持久认证
不要分享或提交您的凭证到版本控制
定期审查并撤销 Google 帐户设置中的未使用访问权限

故障排除

找不到 OAuth 密钥
- 确保 gcp-oauth.keys.json 在当前目录或 ~/.calendar-mcp/
- 检查文件权限
无效的凭证格式
- 确保您的 OAuth 密钥文件包含 web 或 installed 凭证
- 对于 Web 应用程序，请验证重定向 URI 是否正确配置
端口已被占用
- 如果端口 3000 已被占用，请在运行认证前释放它
- 您可以查找并停止使用该端口的过程

贡献

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

许可证

MIT

致谢

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

支持

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