Google Calendar MCP 服务器

一个用于 Google Calendar 的模型上下文协议 (MCP) 实现，允许通过 CLI 或服务器发送事件 (SSE) 与日历事件进行交互。

功能

• 列出日历事件
• 创建新事件
• 更新现有事件
• 删除事件
• 查找可用时间

预requisitos

• Node.js 18 或更高版本
• 具有 Google Calendar API 访问权限的 Google 帐户
• 来自 Google Cloud Console 的 OAuth 2.0 凭据

配置

1. 将 .env.example 文件复制到 .env:

   cp .env.example .env
   

2. 在 .env 文件中配置您的 Google OAuth 2.0 凭据：

   GOOGLE_CLIENT_ID=您的-client-id
   GOOGLE_CLIENT_SECRET=您的-client-secret
   GOOGLE_REDIRECT_URI=http://localhost:3000/oauth2callback
   GOOGLE_REFRESH_TOKEN=您的-refresh-token
   PORT=3334
   

3. 安装依赖项：

   npm install
   

4. 编译代码：

   npm run build
   

使用

作为 HTTP/SSE 服务器执行

启动 HTTP/SSE 服务器：

npm run start:http

这将在指定的端口（默认：3334）上启动服务器。

可用端点：

• GET /sse - 连接到 SSE 流
• POST /messages - 向服务器发送消息

作为 CLI (stdio) 执行

以 stdio 模式运行服务器，用作 CLI 工具：

npm run start:stdio

与 MCP 客户端集成

Claude Desktop

要将此服务器与 Claude Desktop 一起使用，请将以下配置添加到 Claude 的配置文件中：

在 MacOS 上：

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

在 Windows 上：

code %AppData%\Claude\claude_desktop_config.json

添加配置：

{
  "mcpServers": {
    "google-calendar": {
      "command": "node",
      "args": [
        "/绝对路径/到/build/index.js"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "您的-client-id",
        "GOOGLE_CLIENT_SECRET": "您的-client-secret",
        "GOOGLE_REDIRECT_URI": "您的-redirect-uri",
        "GOOGLE_REFRESH_TOKEN": "您的-refresh-token"
      }
    }
  }
}

与其他 MCP 客户端集成

对于支持通过 SSE 通信的其他 MCP 客户端，请将它们指向以下端点：

• SSE 端点：http://localhost:3334/sse
• 消息端点：http://localhost:3334/messages

可用工具

Google Calendar MCP 服务器提供以下工具：

list_events

列出指定时间范围内的事件。

{
  "timeMin": "2023-09-01T00:00:00Z",
  "timeMax": "2023-09-30T23:59:59Z",
  "maxResults": 10
}

create_event

在日历中创建一个新事件。

{
  "summary": "重要会议",
  "description": "关于 XYZ 项目的讨论",
  "startTime": "2023-09-15T14:00:00Z",
  "endTime": "2023-09-15T15:00:00Z",
  "attendees": ["person1@example.com", "person2@example.com"]
}

update_event

更新现有事件。

{
  "eventId": "abc123xyz",
  "summary": "已更新的会议",
  "startTime": "2023-09-15T14:30:00Z",
  "endTime": "2023-09-15T15:30:00Z"
}

delete_event

从日历中删除一个事件。

{
  "eventId": "abc123xyz"
}

find_free_time

查找指定时间范围内的可用时间。

{
  "timeMin": "2023-09-01T00:00:00Z",
  "timeMax": "2023-09-30T23:59:59Z",
  "duration": 60
}

获取 Refresh Token

要从 Google 获取 refresh token，您可以使用以下脚本：

const { google } = require('googleapis');
const http = require('http');
const url = require('url');

// 替换为您的凭据
const CLIENT_ID = '您的-client-id';
const CLIENT_SECRET = '您的-client-secret';
const REDIRECT_URI = 'http://localhost:3000/oauth2callback';

const oauth2Client = new google.auth.OAuth2(
  CLIENT_ID,
  CLIENT_SECRET,
  REDIRECT_URI
);

const scopes = [
  'https://www.googleapis.com/auth/calendar',
  'https://www.googleapis.com/auth/calendar.events'
];

function getRefreshToken() {
  const server = http.createServer(async (req, res) => {
    const queryParams = url.parse(req.url, true).query;
    
    if (queryParams.code) {
      try {
        const { tokens } = await oauth2Client.getToken(queryParams.code);
        console.log('Refresh Token:', tokens.refresh_token);
        res.end('身份验证成功！您可以关闭此窗口。');
        server.close();
      } catch (error) {
        console.error('获取令牌时出错:', error);
        res.end('身份验证失败！');
      }
    }
  }).listen(3000, () => {
    const authUrl = oauth2Client.generateAuthUrl({
      access_type: 'offline',
      scope: scopes,
      prompt: 'consent'
    });

    console.log('在浏览器中访问此 URL：');
    console.log(authUrl);
  });
}

getRefreshToken();

将此脚本保存为 getToken.js，使用 node getToken.js 运行它，并按照说明获取您的 refresh token。

开发

对于开发，您可以运行：

npm run dev

这将以观察模式编译 TypeScript，允许您进行更改并实时查看结果。

故障排除

常见问题

1. Google 身份验证错误

   • 检查您的凭据是否正确
   • 确认 refresh token 是否有效
   • 确保已启用所需的范围

2. 服务器未启动

   • 检查是否已定义所有环境变量
   • 确认构建过程已成功
   • 检查 build/index.js 文件的权限

3. SSE 连接失败

   • 确认端口（默认为 3334）可用
   • 检查日志以获取特定错误
   • 确保端点已正确配置

许可证

ISC