金大哥 - google-calendar MCP 详情

article

README

🚀 Google Calendar MCP 服务器

这是一个用于与 Google Calendar API 对接的最小化协调处理器 (MCP) 服务器，为集成到 Claude Desktop 中提供了所需的接口，可实现日历事件的创建、读取、更新和删除等操作。

🚀 快速开始

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

认证方法

两种认证方式可选：

通过 OAuth2 URL 获取授权链接：

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

直接认证：

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

✨ 主要特性

支持 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

安装步骤

克隆仓库：

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

安装依赖：

npm install
# 或者 yarn

启动服务器：

npm start
# 或者 yarn start

💻 使用示例

基础用法

查询即将进行的事件

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"}}'

📚 详细文档

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：健康检查端点

测试方法

运行测试：

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 密钥和凭证

故障排除

常见问题：

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

贡献指南

如何贡献代码：

Fork 仓库
创建功能分支
提交更改
Pull Request

文档历史

1.0.0 发布于 2024年1月15日

google-calendar