Google Calendar MCP 服务器

简介

这是一个用于与 Google Calendar API 对接的最小化协调处理器 (MCP) 服务器。该服务器为集成到 Claude Desktop 中提供了所需的接口。

特性：

• 支持 OAuth2 身份验证
• 提供多个日历操作端点
• 支持创建、读取、更新和删除事件
• 包含详细的文档和使用示例

安装指南

项目结构

google-calendar-mcp/
├── src/               # 源代码目录
│   ├── server.js      # 主服务器文件
│   ├── routes/        # 路由定义
│   └── controllers/   # 控制器逻辑
├── .env              # 环境变量配置文件
├── Dockerfile       # Docker 构建配置
└── package.json     # 项目依赖和脚本配置

安装依赖

npm install
# 或者使用 yarn
yarn install

配置说明

环境变量

创建 .env 文件，并添加以下内容：

GOOGLE_CLIENT_ID=your_client_id_here
GOOGLE_CLIENT_SECRET=your_client_secret_here
PORT=3000  # 可选，默认为3000

安装步骤

1. 克隆仓库：

   git clone https://github.com/your-repository.git
   cd google-calendar-mcp
   

2. 安装依赖：

   npm install
   # 或者 yarn
   

3. 启动服务器：

   npm start
   # 或者 yarn start
   

快速上手

基本用法

启动服务器后，访问 http://localhost:3000 查看文档。

认证方法

两种认证方式可选：

1. 通过 OAuth2 URL 获取授权链接:

   curl http://localhost:3000/mcp/auth/url
   

2. 直接认证:

   curl -X POST http://localhost:3000/auth/direct
   

API 端点

认证相关

• GET /mcp/auth/url：获取 Google OAuth2 授权链接
• POST /mcp/auth/callback：处理 OAuth2 回调
• POST /auth/direct：直接认证

日历操作

• GET /mcp/calendars：获取所有可用日历列表
• GET /mcp/events：从指定日历获取事件
• GET /mcp/events/upcoming：获取所有日历中的即将进行的事件
• POST /mcp/events/create：创建新事件
• PUT /mcp/events/update：更新现有事件
• DELETE /mcp/events/delete：删除事件
• GET /mcp/events/detail：获取特定事件详情

服务器信息

• GET /mcp/info：获取服务器信息和可用端点
• GET /health：健康检查端点

使用示例

查询即将进行的事件

curl http://localhost:3000/mcp/events/upcoming

创建新事件

请求格式：

{
  "summary": "会议",
  "description": "重要讨论",
  "start": {
    "dateTime": "2024-01-15T10:00:00+08:00"
  },
  "end": {
    "dateTime": "2024-01-15T11:30:00+08:00"
  }
}

发送请求：

curl -X POST http://localhost:3000/mcp/events/create -H "Content-Type: application/json" -d '{"summary":"会议","description":"重要讨论","start":{"dateTime":"2024-01-15T10:00:00+08:00"},"end":{"dateTime":"2024-01-15T11:30:00+08:00"}}'

测试方法

运行测试：

npm test
# 或者 yarn test

Docker 部署

构建镜像：

docker build -t google-calendar-mcp .

运行容器：

docker run -p 3000:3000 --env-file .env google-calendar-mcp

安全考虑

• 确保 .env 文件不被提交到版本控制系统
• 使用 HTTPS 在生产环境中部署
• 定期更新 Google API 密钥和凭证

故障排除

常见问题：

1. 认证失败：检查 GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET 是否正确。
2. 无法连接日历：确保 OAuth2 过程完成并获得有效的访问令牌。

贡献指南

如何贡献代码：

1. Fork 仓库
2. 创建功能分支
3. 提交更改
4. Pull Request

文档历史

• 1.0.0 发布于 2024年1月15日