Strato MCP Google Calendar

平流层MCP谷歌日历

一个Python MCP服务器，将谷歌日历作为人工智能助手的工具公开。目前支持 9个工具： 列出、搜索、获取、创建、更新和删除事件；列出并获取日历；检查忙/闲时间间隔。

兼容Claude、Gemini CLI、OpenAI Codex和任何兼容MCP的客户端。

先决条件

启用Google日历API：

1. 打开 谷歌云控制台
2. 在顶部栏中，从项目选择器中选择现有项目（或创建新项目）
3. 首选 APIs & Services → Library
4. 搜索 Google Calendar API
5. 打开它并单击 Enable

如果您之前已经启用了它，您将看到 Manage 而不是 Enable --你可以走了。

创建OAuth凭据：

1. 首选 APIs & Services → OAuth consent screen 如果尚未配置，请进行配置（选择 *外部的* 供个人使用）
2. 首选 APIs & Services → Credentials → Create credentials → OAuth client ID → Desktop app
3. 复制 Client ID 和 Client Secret --您将把它们添加到您的 .env 下一步

快速入门（Docker）

第一步：构建

docker compose build

步骤2：配置

cp .env.example .env
# Fill in GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET

此文件以纯文本形式包含您的OAuth凭据。限制其权限： chmod 600 .env

步骤3：身份验证（一次）

运行身份验证服务。它会打印一个授权URL。在浏览器中打开它，登录并授予日历访问权限。令牌保存到共享Docker卷，命令退出。

docker compose run --rm -p 8081:8081 auth

第4步：向您的AI助手注册

Claude

克劳德桌面版 --编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "google-calendar": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "google-calendar-mcp-tokens:/tokens",
        "--env-file", "/absolute/path/to/.env",
        "google-calendar-mcp:latest",
        "serve"
      ]
    }
  }
}

替换 /absolute/path/to/.env 与您的完整路径 .env 文件。克劳德桌面版 从未指定的工作目录启动Docker；相对路径不起作用。

克劳德代码：

claude mcp add --transport stdio google-calendar -- \
  docker run --rm -i \
    -v google-calendar-mcp-tokens:/tokens \
    --env-file /absolute/path/to/.env \
    google-calendar-mcp:latest serve

Gemini CLI

编辑 ~/.gemini/settings.json （或 .gemini/settings.json 在项目根目录中为项目范围配置）：

{
  "mcpServers": {
    "google-calendar": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "google-calendar-mcp-tokens:/tokens",
        "--env-file", "/absolute/path/to/.env",
        "google-calendar-mcp:latest",
        "serve"
      ]
    }
  }
}

替换 /absolute/path/to/.env 与您的完整路径 .env 文件。

OpenAI Codex

编辑 ~/.codex/config.toml （或 .codex/config.toml 在项目根目录中为项目范围配置）：

[[mcp_servers]]
name = "google-calendar"
command = "docker"
args = [
  "run", "--rm", "-i",
  "-v", "google-calendar-mcp-tokens:/tokens",
  "--env-file", "/absolute/path/to/.env",
  "google-calendar-mcp:latest",
  "serve"
]

替换 /absolute/path/to/.env 与您的完整路径 .env 文件。

替代方案：本地安装（无Docker）

步骤1：安装

git clone https://github.com/stratosphereips/strato-mcp-google-calendar
cd strato-mcp-google-calendar
uv venv && source .venv/bin/activate
uv pip install -e .

步骤2：配置

cp .env.example .env
# Fill in GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET

此文件以纯文本形式包含您的OAuth凭据。限制其权限： chmod 600 .env

步骤3：身份验证（一次）

运行auth命令。它会打印一个授权URL——在浏览器中打开它，登录， 并授予日历访问权限。令牌保存到 ~/.config/google-calendar-mcp/.

google-calendar-auth

第4步：向您的AI助手注册

Claude

克劳德桌面版 --编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

此文件将以纯文本形式包含您的OAuth凭据。限制其权限 编辑后： chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json.

{
  "mcpServers": {
    "google-calendar": {
      "command": "/absolute/path/.venv/bin/google-calendar-mcp",
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

克劳德代码：

claude mcp add google-calendar /absolute/path/.venv/bin/google-calendar-mcp \
  --env-file /absolute/path/to/.env

避免 --env KEY=VALUE --以这种方式传递的凭据将显示在shell历史记录中 ps.

Gemini CLI

编辑 ~/.gemini/settings.json （或 .gemini/settings.json 在项目根目录中为项目范围配置）：

{
  "mcpServers": {
    "google-calendar": {
      "command": "/absolute/path/.venv/bin/google-calendar-mcp",
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

此文件将以纯文本形式包含您的OAuth凭据。限制其权限 编辑后： chmod 600 ~/.gemini/settings.json.

OpenAI Codex

编辑 ~/.codex/config.toml （或 .codex/config.toml 在项目根目录中为项目范围配置）：

[[mcp_servers]]
name = "google-calendar"
command = "/absolute/path/.venv/bin/google-calendar-mcp"

[mcp_servers.env]
GOOGLE_CLIENT_ID = "your_client_id"
GOOGLE_CLIENT_SECRET = "your_client_secret"

此文件将以纯文本形式包含您的OAuth凭据。限制其权限： chmod 600 ~/.codex/config.toml.

可用工具

配置参考

发展

uv pip install -e ".[dev]"
pytest                        # run all 88 tests

项目结构

src/google_calendar_mcp/
├── server.py          # FastMCP entry point
├── config.py          # Env-var config loading
├── auth/
│   ├── oauth.py       # OAuth flow
│   └── token_store.py # TokenStore ABC + FileTokenStore
├── calendar/
│   ├── client.py      # Google API client factory
│   ├── events.py      # Events API wrappers
│   ├── calendars.py   # CalendarList wrappers
│   └── freebusy.py    # FreeBusy wrapper
└── tools/
    ├── events.py      # MCP tool definitions
    ├── calendars.py
    └── freebusy.py