MCP Google Calendar 服务器

这是一个基于 MCP(模型上下文协议) 的 Google Calendar 集成服务器。它支持像 Claude Desktop 这样的 MCP 客户端向 Google Calendar 添加日程。

功能

• Google OAuth 2.0 认证
• Google Calendar 日程添加
• Google Calendar 日程查询 (支持按时间段查询)
• 今日日期查询
• 韩国时区 (KST) 支持
• 详细的错误处理和日志记录

安装方法

1. 克隆仓库

git clone [repository-url]
cd mcp-server-google-calendar

2. 安装依赖

npm install

3. 设置环境变量 创建 .env 文件并添加以下内容:

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret

Google Cloud Console 设置

1. 在 Google Cloud Console 中创建一个新项目。
2. 启用 Google Calendar API。
3. 创建 OAuth 2.0 客户端 ID:
   • 应用程序类型: "桌面应用"
   • 将生成的客户端 ID 和密钥设置到 .env 文件中

Claude Desktop 联动设置

1. Claude Desktop 安装

   • Claude Desktop 下载
   • MCP 功能仅在桌面应用中可用，网页版本不支持。

2. MCP 服务器设置

   • 创建 ~/Library/Application Support/Claude/claude_desktop_config.json 文件并添加以下内容:

   {
     "mcp-server-google-calendar": {
       "command": "/usr/local/bin/node",
       "args": ["/{绝对路径}/mcp-server-google-calendar/dist/main.js"],
       "env": {
         "GOOGLE_CLIENT_ID": "your_client_id",
         "GOOGLE_CLIENT_SECRET": "your_client_secret",
         "NODE_ENV": "production"
       }
     }
   }
   

   配置项说明:

   • command: Node.js 可执行文件的绝对路径
   • args: 要执行的 JavaScript 文件的绝对路径 (TypeScript 构建后生成的文件)
   • cwd: 项目的工作目录绝对路径
   • env: 环境变量设置
     • GOOGLE_CLIENT_ID: Google Cloud Console 中创建的客户端 ID
     • GOOGLE_CLIENT_SECRET: Google Cloud Console 中创建的客户端密钥
     • NODE_ENV: 运行环境设置

   注意: 以上示例是基于当前安装路径编写的。在其他环境中，需要修改为对应环境的绝对路径。

3. 构建和准备

   # TypeScript 编译
   npm run build
   
   # Node.js 可执行文件位置确认
   which node
   

4. Claude Desktop 重启

   • 为了应用设置，请重启 Claude Desktop。
   • 点击状态图标可以确认服务器连接状态。
   • 如果发生连接问题，请查看日志。

可用工具

googleAuthLogin

执行 Google Calendar API 认证。

// Claude 中使用示例
tool("googleAuthLogin");

addCalendarEvent

向 Google Calendar 添加新的日程。

// Claude 中使用示例
tool("addCalendarEvent", {
  title: "会议",
  startTime: "2024-03-20 15:00", // YYYY-MM-DD HH:mm 格式
  duration: "60", // 分钟单位
});

listCalendarEvents

查询特定时间段的 Google Calendar 日程。

// Claude 中使用示例
tool("listCalendarEvents", {
  period: "2024-03-20~2024-03-27", // YYYY-MM-DD~YYYY-MM-DD 格式
});

getTodayDate

以 YYYY-MM-DD 格式返回今天的日期。

// Claude 中使用示例
tool("getTodayDate");

调试

查看日志

# 实时日志查看
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

启用开发者工具

1. 创建开发者设置文件:

echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json

2. 打开开发者工具: Command-Option-Shift-i

错误处理

服务器在以下情况下会返回适当的错误消息:

• 需要 Google 认证时
• 输入了错误的时间格式时
• 缺少必需的参数时
• Google Calendar API 调用失败时

日志记录

服务器使用 Pino logger 记录以下信息:

• 服务器启动/停止
• 工具调用和响应
• 认证过程
• 错误和异常情况

开发环境设置

1. TypeScript 编译

npm run build

2. 开发模式运行 (自动重启)

npm run dev

3. 语法检查

npm run lint

问题解决

1. 服务器连接问题

   • 查看 Claude Desktop 日志
   • 确认服务器进程运行状态
   • 确认环境变量设置
   • 确认是否使用了绝对路径

2. 认证问题

   • 确认 Google Cloud Console 中 API 启用状态
   • 重新确认客户端 ID 和密钥
   • 确认 OAuth 同意屏幕设置

许可证

MIT License