Google Calendar MCP 服务器

此MCP服务器允许Claude与您的Google日历进行交互，实现诸如列出事件、创建会议和查找空闲时间段等功能。

预备条件

• Node.js (v16或更高版本)
• Claude桌面应用程序
• 一个Google云项目
• 启用Google日历API
• OAuth 2.0凭证

设置指南

1. 创建Google云项目

1. 访问Google云控制台
2. 创建一个新的项目或选择一个现有项目
3. 启用Google日历API：
   • 转到“API和服务” > “库”
   • 搜索“Google日历API”
   • 点击“启用”

2. 配置OAuth同意屏幕

1. 转到“API和服务” > “OAuth同意屏幕”
2. 选择“外部”用户类型（除非您有Google Workspace组织）
3. 填写所需信息：
   • 应用程序名称
   • 用户支持电子邮件
   • 开发者联系信息
4. 添加以下范围：
   • https://www.googleapis.com/auth/calendar
   • https://www.googleapis.com/auth/calendar.events
5. 将您的电子邮件地址添加为测试用户

3. 创建OAuth 2.0凭证

1. 转到“API和服务” > “凭证”
2. 点击“创建凭证” > “OAuth客户端ID”
3. 选择“桌面应用”作为应用程序类型
4. 命名您的客户端（例如，“MCP日历客户端”）
5. 点击“创建”
6. 下载客户端配置文件（您需要客户端ID和客户端密钥）

4. 获取刷新令牌

1. 创建一个名为getToken.js的新文件：

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

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

// 配置OAuth2客户端
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'
];

async function getRefreshToken() {
  return new Promise((resolve, reject) => {
    try {
      // 创建服务器以处理OAuth回调
      const server = http.createServer(async (req, res) => {
        try {
          const queryParams = url.parse(req.url, true).query;
          
          if (queryParams.code) {
            // 从代码中获取令牌
            const { tokens } = await oauth2Client.getToken(queryParams.code);
            console.log('\n=================');
            console.log('刷新令牌：', tokens.refresh_token);
            console.log('=================\n');
            console.log('请将此刷新令牌保存在您的配置中！');
            
            // 发送成功响应
            res.end('身份验证成功！您可以关闭此窗口。');
            
            // 关闭服务器
            server.close();
            resolve(tokens);
          }
        } catch (error) {
          console.error('获取令牌时出错：', error);
          res.end('身份验证失败！请检查控制台中的错误。');
          reject(error);
        }
      }).listen(3000, () => {
        // 生成授权URL
        const authUrl = oauth2Client.generateAuthUrl({
          access_type: 'offline',
          scope: scopes,
          prompt: 'consent'  // 强制显示同意屏幕以确保刷新令牌
        });

        console.log('1. 复制此URL并粘贴到浏览器中：');
        console.log('\n', authUrl, '\n');
        console.log('2. 按照Google的身份验证过程操作');
        console.log('3. 等待刷新令牌在此处出现');
      });

    } catch (error) {
      console.error('创建服务器时出错：', error);
      reject(error);
    }
  });
}

// 运行令牌检索
getRefreshToken().catch(console.error);

2. 安装所需的依赖项：

npm install googleapis

3. 使用您的OAuth凭证更新脚本：

   • 将your-client-id替换为您实际的客户端ID
   • 将your-client-secret替换为您实际的客户端密钥

4. 运行脚本：

node getToken.js

5. 按照控制台中的说明操作：
   • 复制提供的URL
   • 在浏览器中粘贴该URL
   • 完成Google的身份验证过程
   • 复制控制台中出现的刷新令牌

5. 配置Claude桌面

1. 打开您的Claude桌面配置文件：

对于MacOS：

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

对于Windows：

code %AppData%\Claude\claude_desktop_config.json

2. 添加或更新配置：

{
    "mcpServers": {
        "google-calendar": {
            "command": "node",
            "args": [
                "/ABSOLUTE/PATH/TO/YOUR/build/index.js"
            ],
            "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"
            }
        }
    }
}

3. 保存文件并重启Claude桌面

初始项目设置

1. 为您的项目创建一个新目录：

mkdir google-calendar-mcp
cd google-calendar-mcp

2. 初始化一个新的npm项目：

npm init -y

3. 安装依赖项：

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

4. 创建一个tsconfig.json文件：

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

5. 更新package.json：

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

6. 创建您的源目录：

mkdir src

7. 创建一个.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

构建和运行

1. 构建服务器：

npm run build

2. 当您打开Claude桌面时，服务器会自动启动

可用工具

服务器提供以下工具：

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

示例用法在Claude中

设置完成后，您可以使用如下命令：

• "显示我下周的日历事件"
• "明天下午2点安排与[email_id]的1小时会议"
• "找到今天下午的30分钟空档"
• "将我的3点会议改为4点"
• "取消ID为[event_id]的会议"

故障排除

常见问题

1. 工具未出现在Claude中：

   • 检查Claude桌面日志：tail -f ~/Library/Logs/Claude/mcp*.log
   • 验证所有环境变量是否设置正确
   • 确保index.js的路径是绝对且正确的

2. 认证错误：

   • 验证您的OAuth凭证是否正确
   • 检查刷新令牌是否有效
   • 确保已启用所需的范围

3. 服务器连接问题：

   • 检查服务器是否构建成功
   • 验证build/index.js的文件权限（应为755）
   • 尝试直接运行服务器：node /path/to/build/index.js

查看日志

要查看服务器日志：

# 对于MacOS/Linux：
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# 对于Windows：
Get-Content -Path "$env:AppData\Claude\Logs\mcp*.log" -Wait -Tail 20

环境变量

如果您遇到环境变量错误，请验证每个变量：

1. GOOGLE_CLIENT_ID：应以类似“123456789-...”开头
2. GOOGLE_CLIENT_SECRET：通常以“.apps.googleusercontent.com”结尾
3. GOOGLE_REDIRECT_URI：应为“http://localhost”
4. GOOGLE_REFRESH_TOKEN：是一个不会过期的长字符串

安全注意事项

• 保护好您的OAuth凭证
• 不要将凭证提交到版本控制系统
• 使用环境变量存储敏感数据
• 定期轮换刷新令牌
• 监控Google云控制台中的API使用情况

许可

MIT许可 - 详情见LICENSE文件。

支持

如果您遇到任何问题：

1. 查看上面的故障排除部分
2. 查阅Claude桌面日志
3. 在GitHub上打开一个问题
4. 联系维护人员