金大哥 - mcp-google-calendar-and-meet MCP 详情

article

README

🚀 Google Meet MCP Server v3.0 - 生产就绪版

这是一个适用于企业生产环境的模型上下文协议（MCP）服务器，可通过 Google Calendar API v3 和 Google Meet API v2 全面管理 Google Meet。它具备Docker 容器化、Smithery 部署、直接令牌认证、团队安全保障等特性，采用企业级 TypeScript 架构，拥有 23 个经过充分验证的工具。

🚀 快速开始

🔨 Smithery（推荐）

适合团队和个人用户
通过 Web 界面一键部署
自动更新和健康监控
📖 完整的 Smithery 用户指南

🐳 Docker

支持全容器化的生产部署
多阶段构建，优化大小和安全性
提供开发和生产配置
📖 Docker 部署指南

⚙️ 手动设置

可完全控制安装和配置
适用于开发环境和自定义部署
可直接使用 TypeScript 执行 Node.js
📖 手动设置指南

🚀 v3.0 生产就绪版的新特性

🎯 v3.0 新特性 - 生产功能

🐳 Docker 容器化

✅ 多阶段生产构建 - 针对大小和安全性进行优化（<200MB）
✅ 使用 Docker Compose 进行开发和生产配置
✅ 健康检查和监控 - 容器原生健康端点
✅ 安全强化 - 非根用户、只读文件系统
✅ 卷管理 - 持久数据和凭证处理

🔨 Smithery 集成 + 直接令牌认证

✅ 直接令牌认证 - 无需文件依赖（CLIENT_ID、CLIENT_SECRET、REFRESH_TOKEN）
✅ 一键部署 - 通过 Web 界面轻松配置
✅ 向后兼容 - 仍然支持基于文件的 OAuth 凭证
✅ 团队友好设置 - 个人凭证、共享项目结构
✅ 自动健康监控 - 实时服务器状态和指标
✅ 跨平台支持 - 兼容 Windows、macOS、Linux
✅ 配置验证 - 智能路径处理和错误检测

🛡️ 增强的安全性

✅ 团队安全策略 - 企业级凭证管理
✅ 个人凭证隔离 - 用户之间无共享机密
✅ 合规性监控 - 自动安全和轮换跟踪
✅ 审计日志 - 与 Google Cloud Console 集成
✅ 事件响应 - 记录安全事件处理流程

📚 完整文档

✅ 所有部署方法的用户指南 - Smithery、Docker、手动
✅ 团队入职流程 - 适用于企业环境的分步指南
✅ 故障排除和诊断 - 常见问题和自动解决方案
✅ 安全最佳实践 - 个人和团队安全策略

📊 生产质量指标

容器大小：<200MB 生产镜像
安全评分：非根用户、最小攻击面
文档覆盖率：7 份综合指南（2000 + 行）
部署选项：3 种方法（Smithery、Docker、手动）
团队就绪：多用户、企业安全、合规性监控

🎯 核心功能 - 增强版

清晰的 API 分离

📅 Google Calendar API v3 - 全面的日历事件管理，支持嘉宾权限设置
🎥 Google Meet API v2 (GA) - 空间管理、会议记录和参会者跟踪

企业功能

📝 自动转录 - 开启会议自动转录功能
🧠 智能笔记 - 使用 Gemini 生成 AI 会议摘要
📊 考勤报告 - 生成详细的考勤跟踪报告
🛡️ 会议主持 - 聊天/演示限制和控制
👀 观看者模式 - 默认强制参会者以观看者身份加入
📹 自动录制 - 开启自动录制（需手动激活）

高级空间管理

🏗️ Google Meet 空间 - 直接创建和配置空间
👥 参会者跟踪 - 访问参会者数据和会话信息
🔒 访问控制 - 支持 OPEN、TRUSTED 或 RESTRICTED 访问类型
⚙️ 工件配置 - 录制、转录和智能笔记设置

🚀 安装与部署

🔨 Smithery（推荐用于团队）

访问 Smithery.ai
点击“部署服务器”
配置你的 Google 凭证路径
在 Claude Desktop 中开始使用

📖 完整的 Smithery 用户指南 - 团队分步指南

🐳 Docker（推荐用于生产）

# 快速开始开发
./scripts/docker-deploy.sh dev

# 生产部署
./scripts/docker-deploy.sh prod --backup --fresh

# 查看状态
./scripts/docker-deploy.sh status

📖 Docker 部署指南 - 全容器化部署

⚙️ 手动安装

# 克隆仓库
git clone https://github.com/INSIDE-HAIR/google-meet-mcp-server.git
cd google-meet-mcp-server

# 安装依赖
npm install

# 设置 OAuth 凭证
npm run setup

📖 手动设置指南 - 完全控制安装

🛡️ 安全与团队管理

🔐 个人安全

每个用户创建自己的 Google OAuth 凭证
团队成员之间无共享凭证或令牌
使用适当的权限（chmod 600）安全存储文件
📖 安全指南 - 个人安全实践

👥 团队安全

全面的团队入职流程
企业 Google Cloud 项目管理
凭证轮换和合规性监控
📖 团队安全指南 - 企业团队部署

🔧 故障排除

全面的诊断和问题解决
常见问题和解决方案
健康检查脚本和监控
📖 故障排除指南 - 详细问题解决

💻 使用示例

开发模式（TypeScript 热重载）

# 在开发模式下启动服务器
npm run start

# 在 TypeScript 模式下运行设置
npm run setup

生产模式（编译后的 JavaScript）

# 将 TypeScript 编译为 JavaScript
npm run build

# 运行编译后的服务器
npm run start:js

测试

# 运行所有测试
npm test

# 以监听模式运行测试
npm run test:watch

# 生成覆盖率报告
npm run test:coverage

# 仅进行类型检查
npm run type-check

🛠️ 可用工具（共 21 个） - 全部类型安全且经过验证

📅 Google Calendar API v3 工具（6 个工具）

1. `calendar_v3_list_calendars` ✅ 已验证

列出用户可用的所有日历。

验证：无需参数

2. `calendar_v3_list_events` ✅ 已验证

列出即将到来的日历事件，支持过滤选项。

验证：日期格式、最大结果数（1 - 2500）、日历 ID 格式

3. `calendar_v3_get_event` ✅ 已验证

获取特定日历事件的详细信息。

验证：需要 event_id 参数

4. `calendar_v3_create_event` ✅ 已验证

创建新的日历事件，可选择添加 Google Meet 会议。

验证：必填字段、ISO 日期格式、嘉宾权限、持续时间逻辑

参数：

summary（必填）：事件标题
start_time（必填）：ISO 格式的开始时间
end_time（必填）：ISO 格式的结束时间
create_meet_conference（可选）：添加 Google Meet
guest_can_invite_others（可选）：嘉宾邀请权限
guest_can_modify（可选）：嘉宾修改权限
guest_can_see_other_guests（可选）：嘉宾可见权限

5. `calendar_v3_update_event` ✅ 已验证

更新现有日历事件。

验证：需要 event_id，可选更新字段，时间验证

6. `calendar_v3_delete_event` ✅ 已验证

删除日历事件。

验证：需要 event_id 参数

🎥 Google Meet API v2 工具（15 个工具）

7. `meet_v2_create_space` ✅ 已验证

创建具有高级配置的 Google Meet 空间。

验证：访问类型枚举、布尔标志、限制组合

参数：

access_type："OPEN" | "TRUSTED" | "RESTRICTED"（默认："TRUSTED"）
enable_recording：开启自动录制准备
enable_transcription：开启自动转录
moderation_mode："ON" | "OFF" 会议主持模式
chat_restriction：聊天权限控制
present_restriction：演示权限控制

8. `meet_v2_get_space` ✅ 已验证

获取 Google Meet 空间的详细信息。

验证：空间名称格式 (spaces/{space_id})

9. `meet_v2_update_space` ✅ 已验证

更新 Google Meet 空间的配置。

10. `meet_v2_end_active_conference` ✅ 已验证

结束 Google Meet 空间中的活动会议。

验证：空间名称格式验证

11. `meet_v2_list_conference_records` ✅ 已验证

列出历史会议的会议记录。

验证：过滤格式、页面大小限制（1 - 50）

12 - 21. 其他 Meet API 工具 ✅ 全部已验证

meet_v2_get_conference_record - 获取特定会议的详细信息
meet_v2_list_recordings - 列出会议录制文件
meet_v2_get_recording - 获取录制文件的详细信息
meet_v2_list_transcripts - 列出会议转录文件
meet_v2_get_transcript - 获取转录文件的详细信息
meet_v2_list_transcript_entries - 列出转录语音片段
meet_v2_get_participant - 获取参会者的详细信息
meet_v2_list_participants - 列出会议参会者
meet_v2_get_participant_session - 获取会话的详细信息
meet_v2_list_participant_sessions - 列出参会者会话

验证功能：

资源名称格式验证（conferenceRecords/{id}/recordings/{id}）
页面大小限制（根据端点不同为 1 - 1000）
对所有 Google API 资源标识符进行正则表达式验证
分页的智能默认设置

MCP 配置（Claude Desktop）

添加到你的 Claude Desktop 配置中：

{
  "mcpServers": {
    "google-meet": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/google-meet-mcp-server/src/index.ts"],
      "env": {
        "G_OAUTH_CREDENTIALS": "/absolute/path/to/credentials.json"
      },
      "disabled": false
    }
  }
}

生产配置（使用编译后的 JS）：

{
  "mcpServers": {
    "google-meet": {
      "command": "node",
      "args": ["/absolute/path/to/google-meet-mcp-server/build/index.js"],
      "env": {
        "G_OAUTH_CREDENTIALS": "/absolute/path/to/credentials.json"
      },
      "disabled": false
    }
  }
}

🏗️ 企业架构

TypeScript 结构

google-meet-mcp-server/
├── src/
│   ├── index.ts                 # 主 MCP 服务器（TypeScript）
│   ├── GoogleMeetAPI.ts         # API 包装器（完全类型化）
│   ├── setup.ts                 # OAuth 设置（类型化）
│   ├── types/                   # 类型系统（921 + 行）
│   │   ├── google-apis.d.ts        # Google API 类型
│   │   ├── mcp-server.d.ts         # MCP 特定类型
│   │   ├── utilities.d.ts          # 品牌类型和辅助工具
│   │   └── index.ts                # 集中导出
│   ├── validation/              # Zod 模式
│   │   └── meetSchemas.ts          # 6 个已验证的工具
│   └── errors/                  # 错误处理
│       └── GoogleApiErrorHandler.ts
├── test/                        # 测试套件（101 个测试）
│   ├── setup.ts                    # 测试工具
│   ├── GoogleMeetAPI.test.ts       # 单元测试
│   ├── integration.test.ts         # 集成测试
│   ├── validation.test.ts          # 验证测试
│   └── simple.test.ts             # 基本功能测试
├── build/                       # 编译后的 JavaScript
├── package.json                 # TypeScript + 测试依赖
├── tsconfig.json               # TypeScript 配置
└── vitest.config.ts            # 测试配置

类型安全特性

// 增强安全性的品牌类型
type EventId = Brand<string, 'EventId'>;
type SpaceName = Brand<string, 'SpaceName'>;

// 完整的 API 接口
interface GoogleMeetAPI {
  createMeetSpace(config: SpaceConfigInput): Promise<MeetSpace>;
  listCalendars(): Promise<ProcessedCalendar[]>;
  createCalendarEvent(data: CreateEventInput): Promise<ProcessedEvent>;
}

// 带有业务逻辑的 Zod 验证
const CreateSpaceSchema = z.object({
  access_type: z.enum(["OPEN", "TRUSTED", "RESTRICTED"]).default("TRUSTED"),
  enable_recording: z.boolean().default(false)
}).refine((data) => {
  // 自定义业务逻辑验证
  if (data.enable_recording && data.access_type === "OPEN") {
    throw new Error("公开访问的会议不能启用录制功能");
  }
  return true;
});

错误处理 - 针对 Claude Desktop 优化

服务器提供了针对 AI 辅助的上下文感知错误消息：

Google API 错误

🔐 访问被拒绝
问题：你的 Google 账户没有所需的权限。
解决方案：
1. 运行 `npm run setup` 重新进行身份验证
2. 确保你授予了所有请求的权限
3. 对于企业功能，请确保你拥有 Google Workspace Business+ 套餐

企业功能错误

🏢 需要企业功能
问题：此 Meet 功能需要 Google Workspace Business Standard 或更高版本。
选项：
- 改为使用带有 Meet 链接的基本日历事件
- 升级你的 Google Workspace 套餐
替代方案：尝试使用 `calendar_v3_create_event` 并设置 `create_meet_conference: true`

要求

技术要求

Node.js：18+（支持 TypeScript）
TypeScript：5+（包含在依赖项中）
Google 账户：任何 Google 账户均可使用基本功能

功能要求

✅ 基本功能：任何 Google 账户均可使用
✅ 日历集成：需启用 Google Calendar API
🏢 企业功能：需要 Google Workspace Business Standard 或更高版本
🧠 智能笔记：需要 Gemini Business/Enterprise 许可证
📹 录制：会议期间需要手动激活

开发

TypeScript 开发

# 开发时热重载
npm run start          # 使用 watch 模式运行 tsx src/index.ts
npm run setup          # 运行 tsx src/setup.ts

# 类型检查
npm run type-check     # 运行 tsc --noEmit

# 测试
npm test              # 运行 vitest
npm run test:watch    # 以监听模式运行 vitest
npm run test:coverage # 生成覆盖率报告

生产构建

# 编译 TypeScript
npm run build         # 编译到 build/ 目录
npm run clean         # 清理 build 目录

# 运行编译后的 JavaScript
npm run start:js      # 运行 node build/index.js
npm run setup:js      # 运行 node build/setup.js

测试结果

✅ 测试文件：5 个通过（共 5 个）
✅ 测试用例：101 个通过（共 101 个）
✅ 持续时间：2.61 秒
✅ TypeScript：0 个编译错误
✅ 类型覆盖率：约 90% 特定类型

测试类别：
- 28 个 GoogleMeetAPI 单元测试
- 12 个集成工作流测试
- 35 个验证模式测试
- 16 个基本功能测试
- 10 个 MCP 服务器测试

🔧 常见问题与快速修复

🚨 服务器无法启动

# 检查凭证路径和权限
ls -la "/path/to/your/credentials.json"
chmod 600 "/path/to/your/credentials.json"

# 验证配置
npx tsx scripts/health-check.js

🔐 身份验证失败

# 重新运行 OAuth 设置
G_OAUTH_CREDENTIALS="/path/to/creds.json" npm run setup

# 检查 Google Cloud Console：
# 1. 启用的 API（Calendar + Meet）
# 2. 配置的 OAuth 同意屏幕
# 3. 正确设置的范围

🤖 Claude Desktop 问题

# 验证 MCP 配置
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# 重启 Claude Desktop
# 检查 Smithery 中的服务器状态（如果使用）

📖 完整的故障排除指南 - 详细的问题解决方法

企业功能限制

Google Meet API v2

一些高级功能需要 Google Workspace 许可证
无法通过编程方式启动录制（需要手动激活）
智能笔记需要 Gemini Business/Enterprise 许可证
参会者数据仅在会议结束后可用

实现说明

所有 21 个工具均使用官方 Google API 完全实现
高级功能使用直接 REST API 调用 Google Meet API v2
自动处理身份验证和令牌管理
完整的 TypeScript 覆盖，使用品牌类型确保安全

🤝 贡献

开发要求

✅ TypeScript 代码：具有正确的类型（无 'any' 类型）
✅ 测试通过 (npm test) - 保持 100% 测试成功率
✅ 新工具的 Zod 验证模式
✅ 新端点的错误处理
✅ 新功能的文档更新
✅ 凭证处理的安全审查

贡献流程

分叉并克隆 仓库
从 main 分支 创建功能分支
实现更改，并添加测试和文档
运行完整测试套件 (npm test)
更新 docs/ 中的相关指南
提交拉取请求，并提供详细描述

📄 许可证

ISC 许可证 - 可免费用于商业和个人用途。详情请参阅 LICENSE 文件。

🎉 准备好提升你的 Google Meet 工作流程了吗？选择上述部署方法，几分钟内即可开始使用！

💡 推荐：从 Smithery 部署开始，体验最简单的设置过程。

📞 支持与资源

📚 文档

Smithery 用户指南 - 使用 Smithery 进行团队部署
Docker 部署指南 - 容器化生产部署
手动设置指南 - 直接安装和配置
安全指南 - 个人安全最佳实践
团队安全指南 - 企业团队管理
故障排除指南 - 问题诊断和解决

🆘 获取帮助

🐛 GitHub 问题 - 提交 bug 报告和功能请求
🔨 Smithery 支持 - 平台特定帮助
📖 MCP 文档 - 模型上下文协议资源

🎯 快速链接

仓库：github.com/INSIDE-HAIR/google-meet-mcp-server
Smithery 页面：smithery.ai/server/@inside-hair/google-meet-mcp-server
Docker Hub：ghcr.io/inside-hair/google-meet-mcp-server

致谢

基于 Model Context Protocol SDK 构建
由 Google Calendar API 和 Google Meet API 提供支持
与 Claude Desktop 和其他 MCP 客户端兼容
采用企业级 TypeScript 架构
拥有全面的 Zod 验证系统