Google 日历 MCP 服务器 (Python)

本项目实现了一个基于 Python 的 MCP（模型上下文协议）服务器，作为大型语言模型（LLMs）与 Google 日历 API 之间的接口。它使 LLMs 能够通过自然语言请求执行日历操作。

功能

• 认证： 使用 OAuth 2.0（桌面应用程序流，并自动存储/刷新令牌）安全访问 Google 日历 API。
• 核心日历操作：
  • 列出日历 (mcp_google_calendar_list_calendars)。
  • 创建日历 (mcp_google_calendar_create_calendar)。
  • 通过基本和高级过滤查找事件 (mcp_google_calendar_find_events)。
  • 创建详细事件 (mcp_google_calendar_create_event)。
  • 从文本快速添加事件 (mcp_google_calendar_quick_add_event)。
  • 更新事件 (mcp_google_calendar_update_event)。
  • 删除事件 (mcp_google_calendar_delete_event)。
  • 向事件添加参与者 (mcp_google_calendar_add_attendee)。
• 高级调度与分析：
  • 检查参与者的响应状态 (mcp_google_calendar_check_attendee_status)。
  • 查询多个日历的空闲/忙碌信息 (mcp_google_calendar_query_free_busy)。
  • 查找共同的空闲时间段并自动安排会议 (mcp_google_calendar_schedule_mutual)。
  • 分析每日事件数量和持续时间 (mcp_google_calendar_analyze_busyness)。
  • (在任务 3.5 中可能添加了重复事件预测功能，但尚未明确作为一个工具公开)
• 服务器： 基于 FastAPI 的服务器，通过 RESTful API 暴露操作。
• MCP 集成： 使用 mcp_sdk 库通过标准输入输出提供与 MCP 兼容的工具。

设置

1. 先决条件：

   • 安装了 Python 3.8+。
   • 安装了 Git。
   • 可以访问 Google Cloud Platform 项目。

2. 克隆仓库：
   bash
   git clone # 替换为你的仓库 URL
   cd

3. Google Cloud 设置（OAuth 凭证）：

   • 前往 Google Cloud 控制台。
   • 创建一个新项目或选择一个现有项目。
   • 为您的项目启用 Google 日历 API。
   • 导航到“API 和服务” > “凭证”。
   • 点击“+ 创建凭据” > “OAuth 客户端 ID”。
   • 选择 应用程序类型：桌面应用。给它命名（例如，“Calendar MCP Local”）。
   • 点击“创建”。弹出窗口将显示您的 客户端 ID 和 客户端密钥。现在复制这些信息 - 您将在 .env 文件中需要它们。您不需要下载其他应用程序类型提供的 JSON 文件。
   • 配置 OAuth 同意屏幕：
     • 将用户类型设置为“外部”。
     • 填写所需的应用程序信息（应用程序名称、用户支持电子邮件、开发者联系人）。
     • 添加范围：点击“添加或删除范围”，搜索 calendar，添加 .../auth/calendar 范围（读/写权限）。点击“更新”。
     • 添加测试用户：添加您将用于身份验证的 Google 帐户电子邮件地址。
     • 保存并返回仪表板。
   • 返回“API 和服务” > “凭证”，然后点击您创建的桌面应用程序凭据的名称。
   • 在“授权重定向 URI”下，点击“+ 添加 URI”，然后输入 http://localhost:8080/oauth2callback。点击“保存”。（如果您更改了 .env 中的 OAUTH_CALLBACK_PORT，请相应调整端口）。

4. 环境配置（.env 文件）：

   • 在项目的根目录中，复制 env.example 文件并将副本重命名为 .env。

   • 打开 .env 文件并粘贴从 Google Cloud 获取的 客户端 ID 和 客户端密钥：
     dotenv

     Google OAuth 2.0 客户端凭证（来自 Google Cloud 控制台 - 桌面应用程序类型）

     GOOGLE_CLIENT_ID= YOUR_GOOGLE_CLIENT_ID_HERE
     GOOGLE_CLIENT_SECRET= YOUR_GOOGLE_CLIENT_SECRET_HERE

     用户 OAuth 令牌首次认证后存储的文件路径

     该文件会自动生成。默认是 .gcp-saved-tokens.json

     TOKEN_FILE_PATH= .gcp-saved-tokens.json

     OAuth 回调期间本地 Web 服务器的端口（必须与 Google Cloud 重定向 URI 匹配）

     OAUTH_CALLBACK_PORT=8080

     Google 日历 API 范围（默认为读/写权限）

     对于只读访问，请使用 https://www.googleapis.com/auth/calendar.readonly

     CALENDAR_SCOPES= https://www.googleapis.com/auth/calendar* 确保 TOKEN_FILE_PATH 指向应用程序可以写入 token 文件的位置（通常是根目录下的默认文件 .gcp-saved-tokens.json）。此文件会自动添加到 .gitignore 中。

5. 安装依赖项：

   • 在终端中导航到项目目录。

   • 安装所需的 Python 包：
     bash
     pip install -r requirements.txt

   • (建议使用 Python 虚拟环境，但非必需)

运行服务器（用于初始身份验证和测试）

您只需手动运行一次服务器以完成初始的 Google OAuth 身份验证流程。之后，您的 MCP 客户端将根据配置中的命令自动启动服务器。

1. 首次运行（身份验证）：

   • 从终端运行服务器脚本：
     bash
     python run_server.py

   • 脚本会检查保存的 token（.gcp-saved-tokens.json）。由于这些 token 尚不存在，它将：

     • 打印授权 URL。
     • 自动打开浏览器并跳转到该 URL。
     • 引导您登录 Google 帐户并授予日历权限。
     • 授权后，Google 会重定向回本地 URL (http://localhost:8080/oauth2callback)。
     • 脚本捕获授权码并将必要的 token 保存到 .env 文件中指定的位置（.gcp-saved-tokens.json）。

   • 一旦 token 保存成功，脚本通常会启动 FastAPI 服务器（例如，在 http://localhost:8000 上）。在看到 token 已保存或服务器已启动的确认信息后，您可以停止它（Ctrl+C）。

2. 可选：直接测试服务器：

   • 如果您想直接测试 FastAPI 服务器（例如，通过使用 curl 或 Postman 发送 HTTP 请求），可以再次运行 python run_server.py。它将加载保存的 token 并启动服务器，而无需浏览器身份验证。

注意： 对于常规使用 MCP 客户端的情况，在初始身份验证后，您不需要手动运行 python run_server.py。客户端会处理其启动。

MCP 客户端配置（Cursor/Claude Desktop 示例）

要将此服务器作为工具在 MCP 客户端中使用，您需要配置客户端以运行 run_server.py 脚本。这通常在一个 JSON 设置文件中完成。

示例 mcp.json 条目：

json
{
"tools": {
"google_calendar": {
"command": "python",
"args": [
"C:/path/to/your/calendar-mcp/run_server.py"
]
}
}
}

配置详情：

• google_calendar: 您为 MCP 客户端内的此工具实例选择的唯一名称。
• command: 如果 python 在系统的 PATH 中，则设置为 python。否则，请提供 python.exe 或 python 可执行文件的完整绝对路径（例如，/path/to/your/venv/bin/python 或 C:/path/to/your/venv/Scripts/python.exe）。
• args: 提供项目目录中 run_server.py 脚本的完整绝对路径。将占位符 /path/to/your/calendar-mcp/run_server.py 替换为您系统中的实际路径。
• (可选) api: 某些客户端可能仍需要 api 字段来指向底层的 FastAPI 服务器（例如，"api": "http://localhost:8000"），以便进行模式发现，尽管通信是通过 stdio 进行的。
• (可选) timeout: 您可以添加超时时间（例如，"timeout": 30000 表示 30 秒）。

工作原理： 当 MCP 客户端调用此工具时，它会使用指定的 command 和 args 执行。run_server.py 脚本会检测到它是通过管道化的 stdin/stdout 运行的，并自动启动 MCP 通信桥接，而不是仅启动 HTTP 服务器。

重要提示：

• 您的 Google Client ID/Secret 保留在项目的 .env 文件中，不在 MCP 客户端配置中。* 请参阅您特定的MCP客户端文档，以获取确切的配置文件位置和所需字段。

开发

• 代码结构：
  • run_server.py：主入口点，处理服务器启动和MCP检测。
  • src/server.py：FastAPI应用程序定义，HTTP端点。
  • src/calendar_actions.py：与Google Calendar API交互的核心逻辑。
  • src/analysis.py：高级分析功能。
  • src/auth.py：处理OAuth 2.0认证流程和令牌管理。
  • src/models.py：用于请求/响应数据结构的Pydantic模型。
  • src/mcp_bridge.py：使用mcp_sdk实现MCP工具定义，并委托给FastAPI服务器。
• 日志记录： 日志将写入项目根目录下的calendar_mcp.log文件中。
• 测试： （待定）
• 贡献： （待定）

下一步（计划任务）

• 实现MCP资源/提示支持（任务6.1, 6.2）。
• 增强MCP工具参数验证和响应格式化（任务6.3, 6.4）。
• 改进MCP错误处理（任务6.5）。
• 优化开发工作流（任务7）。

许可证

本项目采用双许可模式，以支持开源协作和可持续发展：

1. GNU Affero通用公共许可证v3.0 (AGPL-3.0)：

   • 该软件在AGPLv3许可证条款下免费使用、修改和分发。
   • 主要条件包括衍生作品（包括在网络中使用的修改版本）也必须在AGPLv3下许可，并且其源代码必须公开。
   • 该许可证适用于开源项目或内部使用，在这些情况下遵守AGPLv3是可行的。
   • 请参阅LICENSE文件以获取完整文本。

2. 商业许可证：

   • 如果AGPLv3的条款不适合您的特定用例（例如，将此软件集成到专有、闭源的商业产品或服务中而不遵守AGPLv3的源代码共享要求），则可以提供单独的商业许可证。
   • 有关商业许可选项的查询，请联系deciduusleaf@gmail.com。

通过使用、修改或分发此软件，您同意受AGPLv3或单独协商的商业许可证条款的约束。