谷歌日历 MCP 项目指南

项目概述

此指南详细介绍如何利用 Model Context Protocol (MCP) 创建一个与 Google Calendar 集成的工具，能够在 Claude 中通过自然语言处理来管理和查询日历事件。

环境要求

• 操作系统：支持 Node.js 的任何操作系统（推荐 Linux 或 macOS）
• Node.js 版本：16.0+
• npm 版本：6.0+

快速入门

项目初始化

mkdir google-calendar-mcp
cd google-calendar-mcp
npm init -y

安装依赖

npm install @modelcontextprotocol/sdk googleapis google-auth-library zod
npm install -D @types/node typescript

创建 tsconfig.json 文件

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

更新 package.json

{
  "type": "module",
  "scripts": {
    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\""
  }
}

认证配置

获取 OAuth 凭据

1. 创建 OAuth 应用：

   • 登录 Google Cloud Console
   • 创建新项目或选择现有项目
   • 转到 "APIs & Services" > "Credentials"
   • 点击 "Create Credentials" 并选择 "OAuth client ID"

2. 设置 OAuth 作用域：

   • 请求以下作用域：https://www.googleapis.com/auth/calendar.readonly, https://www.googleapis.com/auth/calendar

配置环境变量

创建一个 .env 文件（不要提交到版本控制系统）：

GOOGLE_CLIENT_ID=your_client_id_here
GOOGLE_CLIENT_SECRET=your_client_secret_here
GOOGLE_REDIRECT_URI=http://localhost
GOOGLE_REFRESH_TOKEN=your_refresh_token_here

项目结构

mkdir src

实现核心功能

导入依赖

在 src/index.ts 中导入必要的模块：

import { GoogleCalendar } from '@modelcontextprotocol/google-calendar';

初始化日历工具

创建一个 MCP 工具类：

export class GoogleCalendarMCP extends Tool {
  private calendar: Calendar;

  constructor() {
    super('google_calendar', 'Google Calendar Management');
    this.calendar = new Calendar({
      client_id: process.env.GOOGLE_CLIENT_ID,
      client_secret: process.env.GOOGLE_CLIENT_SECRET,
      redirect_uri: process.env.GOOGLE_REDIRECT_URI,
      refresh_token: process.env.GOOGLE_REFRESH_TOKEN
    });
  }

  // 实现其他工具方法，如 listEvents, createEvent 等
}

构建与运行

npm run build

可用功能

1. list_events：列出指定时间段内的日历事件
2. create_event：创建新的日历事件
3. update_event：更新现有日历事件
4. delete_event：删除日历事件
5. find_free_time：查找可用的时间段

安全注意事项

• 确保 OAuth 凭据的安全性，不要将其提交到版本控制系统
• 定期轮换刷新令牌
• 监控 Google Cloud Console 中的 API 使用情况

支持与反馈

如遇问题，请按照以下步骤处理：

1. 参考故障排除部分
2. 查看 Claude Desktop 日志
3. 在 GitHub 上创建问题
4. 联系维护人员