AI导哈

Google日历MCP服务

一个将Google日历作为AI助手工具的Python MCP服务器，支持列出、搜索、获取、创建、更新和删除事件等9种功能。

  • by stratosphereips
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 stratosphereips/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.

可用工具

工具 说明
list_events_tool 从日历中列出即将发生的事件
search_events_tool 跨事件的全文搜索
get_event_tool 按ID检索单个事件
create_event_tool 创建新事件
update_event_tool 修补现有事件
delete_event_tool 删除事件
list_calendars_tool 列出所有日历
get_calendar_tool 获取一个日历的详细信息
check_free_busy_tool 跨日历查询繁忙时间间隔

配置参考

变量 必填 默认 描述
GOOGLE_CLIENT_ID 是 -- OAuth客户端ID
GOOGLE_CLIENT_SECRET 是 -- OAuth客户端密钥
GOOGLE_REDIRECT_URI 没有 http://localhost:8081 OAuth重定向URI
TOKEN_STORE_PATH 没有 ~/.config/google-calendar-mcp/ （当地）； /tokens （Docker） Token存储目录
GOOGLE_SCOPES 没有 https://www.googleapis.com/auth/calendar OAuth作用域（逗号分隔）。默认情况下授予完全读/写访问权限（创建、更新、删除）。用于只读访问 https://www.googleapis.com/auth/calendar.readonly.
DEFAULT_CALENDAR_ID 没有 primary 默认日历
LOG_LEVEL 没有 WARNING 日志级别（仅限stderr）

发展

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

相关 MCP