ai-scheduler-mcp

这是一个用于集成 Google Tasks 和 Calendar API 的 MCP（模型上下文协议）服务器。MCP 客户端（例如 Roo Code）可以使用它来利用 Google Tasks 和 Calendar 的功能。

前提条件

• 必须安装 Docker。
• 必须存在名为 mcp-network 的 Docker 网络。

  # 如果不存在，请使用以下命令创建
  docker network create mcp-network
  

设置

1. 准备仓库: 克隆或下载此仓库。

2. 准备凭据 (credentials.json):

   • 在 Google Cloud Console 中创建一个 OAuth 2.0 客户端 ID（“桌面应用”或“Web 应用程序”类型）。创建时，请确保启用 Google Tasks API 和 Google Calendar API。
   • 以 JSON 格式下载创建的凭据，并将文件名保存为 credentials.json，然后将其保存在此项目的根目录 (ai-scheduler-mcp/) 中。
   • 重要提示: credentials.json 是机密信息。绝对不要将其提交到 Git 仓库。（它包含在 .gitignore 中）

3. 构建 Docker 镜像: 使用 scripts/ai-scheduler-mcp.sh 脚本来管理项目。为了简化命令，建议参考 便捷用法（别名） 部分来设置别名（例如 ai_scheduler_mcp）。 使用以下命令构建 Docker 镜像（设置别名后）：

   ai_scheduler_mcp build
   

首次认证（生成 token.json）

首次使用服务器之前，您需要使用 Google 帐户进行身份验证，并生成 API 访问所需的 token.json。

1. 运行以下命令：

   ai_scheduler_mcp start-auth
   

   （如果需要更改端口，请添加 -P <端口号> 选项）

2. 控制台中将显示一个身份验证 URL，请在 Web 浏览器中访问该 URL，使用您的 Google 帐户登录并批准请求的权限。

3. 批准后，复制显示的身份验证代码，然后按照控制台中的说明粘贴该代码并按 Enter 键。

4. 身份验证成功后，将在项目根目录中生成 token.json。

   • 重要提示: token.json 也是机密信息。绝对不要将其提交到 Git 仓库。（它包含在 .gitignore 中）

正常启动

首次身份验证完成并生成 token.json 后，可以使用以下命令启动服务器。

# 使用默认设置启动
ai_scheduler_mcp start

# 使用端口 8080 和重启策略 always 启动
ai_scheduler_mcp start -P 8080 -r always

服务器将在后台启动。

基本用法（使用别名）

# 停止并删除服务器（容器）
ai_scheduler_mcp stop

# 显示服务器日志（按 Ctrl+C 退出）
ai_scheduler_mcp logs

# 停止并删除容器，并删除镜像（需要确认）
ai_scheduler_mcp delete

# 显示帮助
ai_scheduler_mcp help

来自 MCP 客户端的连接（Roo Code 示例）

如果从主机连接，请在 Roo Code 的 MCP 设置（MCP Servers -> 编辑 MCP 设置）中添加以下内容（PORT 是服务器的启动端口）：

{
  "mcpServers": {
    "ai-scheduler-mcp-server": {
      "url": "http://localhost:${PORT}/sse"
    }
  }
}

对于默认端口 (3003)，它将是 http://localhost:3003/sse。

从开发容器连接（通过主机）

如果需要从开发容器（或其他未加入此 MCP 服务器所在的 Docker 网络 (mcp-network) 的容器）进行连接，请通过主机进行连接。

连接 URL 将是 http://<host_ip_or_dns_name>:<PORT>/sse。

• Docker Desktop (Mac/Windows): 使用特殊的 DNS 名称 host.docker.internal。
  • 例如: http://host.docker.internal:3003/sse
• Linux: 使用主机的 IP 地址或 Docker 网桥网络的网关 IP（通常为 172.17.0.1）。
  • 例如: http://172.17.0.1:3003/sse

Roo Code 的 MCP 设置示例 (Docker Desktop):

{
  "mcpServers": {
    "ai-scheduler-mcp-server": {
      "url": "http://172.17.0.1:3003/sse"
    }
  }
}

注意: <PORT> 必须替换为服务器实际在主机上公开的端口号。Linux 的 IP 地址因环境而异。还请检查主机的防火墙设置。

便捷用法（别名）

每次都输入 ./scripts/ai-scheduler-mcp.sh 比较麻烦，可以在 shell 的配置文件（~/.bashrc、~/.zshrc 等）中定义别名来简化操作。

# 例如: 创建一个名为 ai_scheduler_mcp 的别名
alias ai_scheduler_mcp="/path/to/your/project/ai-scheduler-mcp/scripts/ai-scheduler-mcp.sh" # <- 更改为实际路径

重新加载配置文件（例如 source ~/.bashrc）后，您可以使用 ai_scheduler_mcp build 等较短的命令来执行脚本。

TIPS / 其他信息

• 直接操作 Docker: 您也可以直接使用 docker build、docker run 命令。有关详细信息，请参阅 scripts/ai-scheduler-mcp.sh 的内容或 Docker 文档。
• 容器间连接: 从加入同一 mcp-network 的其他容器，可以使用 http://ai-scheduler-mcp-server:${PORT}/sse 进行连接。
• 通信协议: 此服务器使用 SSE（服务器发送事件）。
• 环境变量: 端口号等也可以通过环境变量 (PORT) 进行设置。