使用说明

项目简介

testCal MCP服务器是一个自定义的MCP服务器，旨在通过集成Google日历API，为LLM（大型语言模型）客户端提供日历管理能力。它允许LLM客户端通过预定义的工具来创建新的日历事件和搜索现有事件，从而扩展LLM在日程安排和信息检索方面的应用。

主要功能点

创建日历事件 (create-event): 允许LLM客户端在Google日历中创建新的事件，需要提供事件标题、开始时间、结束时间等信息，并支持添加参与者。时间格式需为ISO 8601 UTC时间。
搜索日历事件 (search-events): 允许LLM客户端在指定时间范围内搜索Google日历事件，可以根据关键词进行筛选。时间范围需为ISO 8601 UTC时间。

安装步骤

安装依赖: 确保你的系统已安装Python和pip，推荐使用uv进行包管理。

pip install uv # 如果没有安装uv
uv sync

配置Google OAuth2 客户端:
- 前往 Google Cloud Console 创建一个Google Cloud项目。
- 在项目中启用 "Google Calendar API"。
- 创建 OAuth 2.0 客户端ID，应用类型选择“桌面应用”。
- 下载客户端ID和客户端密钥的JSON文件，并将其重命名为 'credentials.json'，保存到仓库根目录下。

服务器配置

为了让MCP客户端（例如Claude Desktop）连接到testCal MCP服务器，你需要在客户端的配置文件中添加服务器配置信息。以下是针对 Claude Desktop 的配置示例，你需要根据你的实际环境进行调整。

找到 Claude Desktop 配置文件：

MacOS: '~/Library/Application Support/Claude/claude_desktop_config.json'
Windows: '%APPDATA%/Claude/claude_desktop_config.json'

在 'claude_desktop_config.json' 文件的 'mcpServers' 部分添加或修改 'testCal' 服务器配置。 请注意，以下配置中的路径 '/Users/avijitsarkar/Library/Application Support/Claude/testCal' 需要替换为你实际的仓库路径。

开发/未发布服务器配置 (Development/Unpublished Servers Configuration):

"mcpServers": {
  "testCal": {
    "command": "uv",
    "args": [
      "--directory",
      "/Users/avijitsarkar/Library/Application Support/Claude/testCal",  // 替换为你的仓库路径
      "run",
      "testCal"
    ]
  }
}

'server name': 'testCal' (服务器名称，客户端配置中用于标识)
'command': 'uv' (启动服务器的命令，这里使用uv运行)
'args': 启动命令的参数列表
- '--directory': 指定服务器代码所在的目录，请务必替换为你的仓库路径。
- 'run': uv 的子命令，用于运行 Python 包。
- 'testCal': 指定要运行的 Python 包名称，对应 'src/testcal/init.py'。

发布服务器配置 (Published Servers Configuration): 如果你已经将服务器打包并发布，可以使用以下配置 (本例中 'testCal' 假设为已发布的包名，实际情况可能需要调整):

"mcpServers": {
  "testCal": {
    "command": "uvx",
    "args": [
      "testCal"
    ]
  }
}

'server name': 'testCal'
'command': 'uvx' (用于运行已发布的包)
'args': 运行命令的参数列表
- 'testCal': 已发布的包名称。

基本使用方法

启动服务器: 配置完成后，MCP服务器会随着MCP客户端（如Claude Desktop）的启动而自动启动。你也可以在仓库根目录下手动运行服务器：
```
uv run src/testcal/server.py
```
在MCP客户端中使用工具: 在支持MCP协议的LLM客户端中，你可以指示LLM使用 'create-event' 和 'search-events' 工具来操作你的Google日历。例如，你可以向LLM客户端发送指令：
- "创建一个明天上午10点到11点的会议，主题是项目讨论，参与者是 [email protected]" (LLM客户端会解析指令并调用 'create-event' 工具)
- "搜索下周的日程安排" (LLM客户端会调用 'search-events' 工具，并根据上下文确定时间范围)

注意: 首次运行服务器时，会通过OAuth2流程请求Google日历的访问权限，需要在浏览器中完成授权。授权成功后，凭据将保存在 'token.pickle' 文件中，后续运行将自动使用已授权的凭据。

关键词