🚀 谷歌日历 MCP 项目指南

本项目旨在创建一个与 Google Calendar 集成的工具，借助 Model Context Protocol (MCP) 以及自然语言处理能力，让你能在 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

✨ 主要特性

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

🔧 技术细节

本项目借助 Model Context Protocol (MCP) 实现与 Google Calendar 的集成，通过自然语言处理技术，允许用户在 Claude 中管理和查询日历事件。项目使用 Node.js 作为运行环境，依赖 @modelcontextprotocol/sdk、googleapis、google-auth-library 和 zod 等库。

⚠️ 重要提示

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

📚 详细文档

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

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