使用说明

谷歌日历MCP服务器

一种模型上下文协议（MCP）服务器，为人工智能助手提供对谷歌日历的安全访问。

使用TypeScript构建，用于类型安全和现代开发实践。

目的

此MCP服务器为AI助手提供了一个安全的接口来管理Google日历事件，包括创建、读取、更新和删除事件。

特性

当前实施情况

list_events -使用可选的时间范围筛选列出即将发生的日历事件
create_event -创建包含标题、时间、地点和与会者的新日历事件
update_event -更新现有事件详细信息
delete_event -删除日历事件
search_events -按关键字搜索事件
list_calendars -列出所有可用日历
get_event -获取特定事件的详细信息

先决条件

Node.js 20或更高版本
启用MCP工具包的Docker桌面
Docker MCP CLI插件(docker mcp 命令）
启用日历API的Google云控制台项目
OAuth 2.0凭据（credentials.json）
OAuth令牌（通过身份验证流程生成）

Google日历API设置

第一步：创建谷歌云项目

首选谷歌云控制台
创建新项目或选择现有项目
启用Google日历API：
- 导航到“API和服务”>“库”
- 搜索“Google日历API”
- 点击“启用”

步骤2：创建OAuth 2.0凭据

导航到“API和服务”>“凭据”
点击“创建凭据”>“OAuth客户端ID”
选择“桌面应用程序”作为应用程序类型
下载凭据JSON文件
另存为 credentials.json 在项目根中

步骤3：生成令牌

# Install dependencies
npm install

# Run authentication script
npm run auth

这将：

打开浏览器窗口
要求您登录您的Google帐户
请求日历权限
将令牌保存到 token.json

安装

第一步：构建项目

npm install
npm run build

第二步：构建Docker镜像

docker build -t google-calendar-mcp-server .

步骤3：设置Docker MCP

凭据和令牌文件将直接从项目目录装载到容器中。

步骤4：创建自定义目录

创建或编辑 ~/.docker/mcp/catalogs/custom.yaml:

version: 3
name: custom
displayName: Custom MCP Servers
registry:
  google-calendar:
    description: "Google Calendar MCP Server with OAuth2 authentication for managing calendar events and tasks"
    title: "Google Calendar"
    type: server
    dateAdded: "2025-11-26T00:00:00Z"
    image: google-calendar-mcp-server:latest
    ref: ""
    readme: ""
    toolsUrl: ""
    source: ""
    upstream: ""
    icon: ""
    tools:
      - name: list_events
      - name: create_event
      - name: update_event
      - name: delete_event
      - name: search_events
      - name: list_calendars
      - name: get_event
    prompts: 0
    resources: {}
    volumes:
      - "/Users/YOUR_USERNAME/path/to/mcp-server-google-calendar/credentials.json:/app/credentials.json:ro"
      - "/Users/YOUR_USERNAME/path/to/mcp-server-google-calendar/token.json:/app/token.json:ro"
    env:
      - name: GOOGLE_CALENDAR_CREDENTIALS_PATH
        value: "/app/credentials.json"
      - name: GOOGLE_CALENDAR_TOKEN_PATH
        value: "/app/token.json"
    metadata:
      category: productivity
      tags:
        - calendar
        - google
        - oauth2
        - scheduling
        - events
      license: MIT
      owner: local

步骤5：更新注册表

编辑 ~/.docker/mcp/registry.yaml:

registry:
  google-calendar:
    ref: ""

步骤6：测试服务器

验证服务器是否可用：

docker mcp server list

你应该看看 google-calendar 在列表中。

步骤7：使用工具

您现在可以通过任何MCP客户端或直接通过Docker MCP CLI使用Google日历工具：

# List all available tools
docker mcp tools ls

# Example: List events
docker mcp tools call list_events '{"maxResults": "5"}'

# Example: Create an event
docker mcp tools call create_event '{
  "summary": "Team Meeting",
  "start": "2025-11-27T14:00:00",
  "end": "2025-11-27T15:00:00"
}'

# Example: Search events
docker mcp tools call search_events '{"query": "meeting"}'

发展

本地开发

# Install dependencies
npm install

# Run in development mode with auto-reload
npm run dev

# Type check
npm run typecheck

# Build
npm run build

# Run production build
npm start

局部测试

# Set environment variables for testing
export GOOGLE_CALENDAR_CREDENTIALS_PATH="./credentials.json"
export GOOGLE_CALENDAR_TOKEN_PATH="./token.json"

# Run directly
npm start

使用示例

使用Docker MCP CLI：

# List today's events
docker mcp tools call list_events '{"maxResults": "10"}'

# Create a new event
docker mcp tools call create_event '{
  "summary": "Team Sync",
  "start": "2025-11-27T14:00:00",
  "end": "2025-11-27T15:00:00",
  "description": "Weekly team sync meeting"
}'

# List all calendars
docker mcp tools call list_calendars '{}'

# Search for events
docker mcp tools call search_events '{"query": "project review"}'

# Get event details
docker mcp tools call get_event '{"eventId": "xyz123"}'

# Delete an event
docker mcp tools call delete_event '{"eventId": "xyz123"}'

# Update an event
docker mcp tools call update_event '{
  "eventId": "xyz123",
  "start": "2025-11-27T15:00:00"
}'

建筑

MCP Client/CLI → Docker MCP Toolkit → Google Calendar MCP Server → Google Calendar API
                                              ↓
                                   Volume-mounted credentials
                                (credentials.json + token.json)

TypeScript的好处

类型安全：在编译时捕获错误
更好的IDE支持：增强的自动补全和重构
现代JavaScript：使用最新的ECMAScript功能
可维护性：具有类型的自文档化代码

安全考虑

所有凭据都存储在卷装载文件中
从不硬编码凭据
以非root用户身份运行
从未记录敏感数据
所有参数的输入验证
API调用的超时保护
OAuth 2.0令牌刷新已自动处理

故障排除

工具未出现

验证Docker镜像构建成功： docker images | grep google-calendar
检查目录文件语法： cat ~/.docker/mcp/catalogs/custom.yaml
验证注册表项： cat ~/.docker/mcp/registry.yaml
检查服务器列表： docker mcp server list

构建错误

检查TypeScript版本兼容性
跑 npm run typecheck 查看类型错误
确保安装了所有依赖项

身份验证错误

验证credentials.json是有效的OAuth 2.0客户端配置
确保token.json存在且未过期
重新运行 npm run auth 重新生成令牌
检查文件路径是否与环境变量匹配

API错误

验证Google日历API是否已在云控制台中启用
检查OAuth范围是否包括日历访问
确保令牌未被撤销

令牌刷新

当OAuth令牌过期时，服务器会自动刷新它们。如果遇到持续的身份验证错误：

删除 token.json
跑 npm run auth 再次
新令牌将由服务器自动拾取（由于它是卷装载的，因此不需要重建）

许可证

MIT许可证