Google Calendar MCP Server (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)。
  • 创建详细事件 (m_ 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库使用stdio提供兼容MCP的工具。

安装

1. 前提条件：

   • 已安装Python 3.8+。
   • 已安装Git。
   • 可以访问Google云平台项目。

2. 克隆仓库：

   git clone <repository-url> # 替换为您的仓库URL
   cd <repository-directory>
   

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

   • 访问Google云控制台。
   • 创建新项目或选择现有项目。
   • 启用您的项目的Google日历API。
   • 导航到“API和服务” > “凭据”。
   • 点击“+ 创建凭据” > “OAuth客户端ID”。
   • 选择应用类型：桌面应用。给它命名（例如，“日历MCP本地”）。
   • 点击“创建”。弹出窗口会显示您的客户端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云获取的客户端ID和客户端密钥：

     # Google OAuth 2.0客户端凭证（来自Google云控制台 - 桌面应用类型）
     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云重定向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指向应用程序可以写入令牌文件的位置（通常根目录下的默认.gcp-saved-tokens.json即可）。此文件会被自动添加到.gitignore。

5. 安装依赖项：

   • 在终端中导航到项目目录。
   • 安装所需的Python包：

     pip install -r requirements.txt
     

   • (建议但非强制使用Python虚拟环境)

运行服务器（初始认证及测试）

您只需要手动运行服务器一次来完成初始的Google OAuth认证流程。之后，您的MCP客户端将根据其配置自动启动服务器。

1. 首次运行（认证）：

   • 从终端运行服务器脚本：

     python run_server.py
     

   • 脚本检查已保存的令牌（.gcp-saved-tokens.json）。由于它们还不存在，它将：
     • 打印一个授权URL。
     • 自动打开浏览器到该URL。
     • 引导您登录Google账户并授予日历权限。
     • 授予权限后，Google会重定向回本地URL（http://localhost:8080/oauth2callback）。
     • 脚本捕获授权码并将必要的令牌保存到.env指定的文件（.gcp-saved-tokens.json）。
   • 一旦令牌被保存，脚本通常会启动FastAPI服务器（如http://localhost:8000）。您可以通常在看到令牌已保存或服务器已启动的确认后停止它（Ctrl+C）。

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

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

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

MCP客户端配置（示例用于Cursor/Claude桌面）

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

示例mcp.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客户端ID/密钥安全地存储在项目.env文件中，不在MCP客户端配置中。
• 咨询特定MCP客户端的文档以了解确切的配置文件位置和所需字段。

开发

• 代码结构：
  • run_server.py：主入口点，处理服务器启动和MCP检测。
  • src/server.py：FastAPI应用程序定义，HTTP端点。
  • src/calendar_actions.py：与Google日历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或单独协商的商业许可证条款的约束。