项目简介

本项目 'mcp_gcal' 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在为大型语言模型 (LLM) 提供访问 Google Calendar 的能力。通过此 MCP 服务器，LLM 可以查询用户的日历事件、查找空闲时间段以及进行时区转换等操作，从而实现更加智能和实用的日历相关应用。

主要功能点

获取时区差异 (get_timezone_difference): 计算两个时区之间的小时差。
查询注册表邮箱 (lookup_registry_email): 根据姓名从注册表 API 中查找用户的电子邮件地址。
检索日历事件 (retrieve_calendar_events): 获取指定日历（默认为用户的主日历）的未来事件列表。
检索日历忙闲时段 (retrieve_calendar_free_busy_slots): 查询指定时间范围内，多个日历的忙闲时段，用于会议安排等场景。
检索日历时区 (retrieve_timezone): 获取指定日历的时区信息。

安装步骤

环境准备: 确保已安装 Python 3.8+ 和 uv (或 pip)。推荐使用 uv 进行包管理以获得更快的速度。

克隆仓库: 将 'mcp_gcal' 仓库克隆到本地。

git clone https://github.com/alejandrosalinas/mcp_gcal.git
cd mcp_gcal

安装依赖: 使用 uv 安装项目依赖。如果尚未安装 uv，请先安装 uv (https://astral.sh/uv)。
```
uv sync
```
或者，如果使用 pip：
```
pip install -r requirements.txt
```

激活虚拟环境: 激活 Python 虚拟环境。

source .venv/bin/activate

配置 Google Calendar API 凭据:
- 本项目需要访问 Google Calendar API。您需要在 Google Cloud Platform 上创建一个项目，启用 Calendar API，并下载 'credentials.json' 文件。具体步骤请参考 Google Calendar API 的官方文档。
- 设置环境变量 'GCAL_CREDENTIALS_PATH' 和 'GCAL_TOKEN_PATH' 指向您的凭据文件和 token 文件路径。例如，可以将 'credentials.json' 放置在 '~/.config/goose/mcp-gcal/credentials.json'，并设置环境变量：
```
export GCAL_CREDENTIALS_PATH="/Users/your_username/.config/goose/mcp-gcal/credentials.json"
export GCAL_TOKEN_PATH="/Users/your_username/.config/goose/mcp-gcal/token.json"
```
  注意: 请替换 '/Users/your_username/' 为您的实际用户目录。首次运行时，服务器会自动打开浏览器进行 OAuth 2.0 授权。授权成功后，token 信息将保存在 'GCAL_TOKEN_PATH' 指定的文件中。

服务器配置

为了让 MCP 客户端（如 Goose）连接到 'mcp_gcal' 服务器，您需要提供以下配置信息。在 Goose 中，您需要在 Settings > Extensions > Add 中添加扩展，类型选择 StandardIO，并配置以下信息：

{
  "serverName": "mcp_gcal",
  "command": "/path/to/mcp_gcal/.venv/bin/mcp_gcal",
  "args": []
}

配置参数说明:

'serverName': 服务器名称，可以自定义，例如 "mcp_gcal"。
'command': 必须修改为您的 'mcp_gcal' 项目虚拟环境中的 'mcp_gcal' 可执行文件的绝对路径。 您可以使用 'which mcp_gcal' 命令在激活虚拟环境后查找该路径。例如：'/Users/your_username/mcp_gcal/.venv/bin/mcp_gcal'。
'args': 启动服务器的参数，本项目不需要额外的启动参数，所以为空数组 '[]'。

基本使用方法

启动 MCP 服务器: 在项目根目录下，激活虚拟环境后，运行以下命令启动服务器：
```
mcp_gcal
```
服务器默认在端口 3000 运行，启动后不会有明显的日志输出，但会在后台运行。
在 MCP 客户端中使用: 配置好 MCP 客户端（如 Goose）后，客户端将自动检测到 'mcp_gcal' 服务器提供的工具。您可以在客户端中通过自然语言指令或图形界面调用这些工具，例如：
- "查询我明天的日程安排" (对应 'retrieve_calendar_events' 工具)
- "查找今天下午3点到5点我的空闲时间" (对应 'retrieve_calendar_free_busy_slots' 工具)
- "北京和纽约的时差是多少？" (对应 'get_timezone_difference' 工具)
具体的调用方式取决于 MCP 客户端的功能和界面。请参考您使用的 MCP 客户端的文档。

注意:

首次使用需要完成 Google Calendar API 的 OAuth 2.0 授权。
确保环境变量 'GCAL_CREDENTIALS_PATH' 和 'GCAL_TOKEN_PATH' 配置正确，并且凭据文件存在。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息