MCP 服务器

Google Calendar AutoAuth MCP Server

使 AI 助手能够通过自然语言交互来管理 Google 日历，其功能包括创建、更新和删除事件、搜索日历以及支持自然语言日期/时间输入。

README

Google Calendar AutoAuth MCP 服务器

一个用于 Claude Desktop 中 Google Calendar 集成的模型上下文协议 (MCP) 服务器，支持自动身份验证。该服务器使 AI 助手能够通过自然语言交互管理 Google Calendar。

功能

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

安装与身份验证

手动安装

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

a. 创建一个 Google Cloud 项目：
- 前往 Google Cloud Console
- 创建一个新项目或选择一个现有项目
- 为您的项目启用 Google Calendar API
b. 创建 OAuth 2.0 凭据：
- 前往“API 和服务”>“凭据”
- 点击“创建凭据”>“OAuth 客户端 ID”
- 选择“桌面应用”或“Web 应用程序”作为应用程序类型
- 给它一个名称并点击“创建”
- 对于 Web 应用程序，将 http://localhost:3000/oauth2callback 添加到授权重定向 URI
- 下载客户端 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/ 中，并且可以从任何目录使用
- 支持桌面应用和 Web 应用程序凭据
- 对于 Web 应用程序凭据，请确保将 http://localhost:3000/oauth2callback 添加到您的授权重定向 URI
在 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": ["colleague@example.com", "manager@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 已被使用，请在运行身份验证之前释放它
- 您可以找到并停止使用该端口的进程