Google Calendar MCP App

谷歌日历mcp应用程序

带有交互式用户界面的谷歌日历——就在你的人工智能聊天中。

向你的人工智能助手询问你的日程安排，并获得真实的交互式日历视图，而不是纯文本。使用表单创建活动。以可视化热图的形式查看您的可用性。所有内容都在对话中内联呈现。

快速开始

1.克隆和安装

git clone https://github.com/QuantGeekDev/google-calendar-mcp-app.git
cd google-calendar-mcp-app
npm install
npm run build

2.设置谷歌日历访问

您需要OAuth凭据才能访问Google日历API。设置此项的两种方法：

选项A：使用 gcloud CLI（最快）

如果你有 谷歌云CLI 安装：

# Create project and enable Calendar API
gcloud projects create my-gcal-mcp --name="Google Calendar MCP"
gcloud config set project my-gcal-mcp
gcloud services enable calendar-json.googleapis.com

然后在浏览器中完成（点击2次）：

1. 配置同意屏幕 --打开 OAuth 授权界面，选择“外部”，填写应用程序名称+您的电子邮件，跳过范围，将自己添加为测试用户
2. 创建凭据 --打开 创建OAuth客户端，选择“桌面应用程序”，创建，下载JSON

将下载的文件另存为 gcp-oauth.keys.json 在项目根中。

选项B：全部在浏览器中

1. 首选 谷歌云控制台 → 创建一个项目
2. 搜索 “Google日历API” → 启用它
3. 首选 API和服务→ OAuth 授权界面 → 外部→ 填充基础→ 将自己添加为测试用户
4. 首选 凭证→ 创建凭证→ OAuth客户端ID→ 桌面应用程序 → 下载JSON
5. 另存为 gcp-oauth.keys.json 在项目根中

3.身份验证

export GOOGLE_OAUTH_CREDENTIALS=./gcp-oauth.keys.json
npm run auth

浏览器窗口打开——使用您的谷歌帐户登录并授予日历访问权限。令牌保存在本地。您只需要执行一次（令牌自动刷新）。

提示： 如果您看到“此应用程序未验证”，请单击 高级→ 转到\[应用程序名称\]（不安全）。这对于测试模式应用程序来说是正常的。

4.连接到您的AI主机

Claude Desktop（推荐-完全支持MCP应用程序UI）

添加 ~/.config/Claude/claude_desktop_config.json （Linux）或 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）：

{
  "mcpServers": {
    "google-calendar": {
      "command": "node",
      "args": ["/absolute/path/to/google-calendar-mcp-app/build/index.js"],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/absolute/path/to/gcp-oauth.keys.json"
      }
    }
  }
}

重新启动克劳德桌面。问： *“这周我的日程表上有什么？”*

MCPJam检查员（最适合测试和开发）

# Terminal 1: start the MCP server
export GOOGLE_OAUTH_CREDENTIALS=./gcp-oauth.keys.json
npm run start:http -- --port 3001 --host 0.0.0.0

# Terminal 2: launch MCPJam
npx @mcpjam/inspector@latest

打开http://localhost:6274，单击 添加服务器→ HTTP，输入 http://127.0.0.1:3001，连接。选择任何工具并调用它——交互式UI将内联呈现。

VS代码（GitHub副本）

VS Code with GitHub Copilot支持MCP应用程序。在VS Code的MCP设置中添加服务器，并使用Copilot Chat。

Claude.ai（仅限web，无UI渲染）

# Start HTTP server
npm run start:http -- --port 3001 --host 0.0.0.0

# Tunnel to the internet
npx cloudflared tunnel --url http://localhost:3001

# Copy the tunnel URL → claude.ai → Settings → Connectors → Add custom connector

注意：Claude.ai网站目前仅显示文本回复。交互式UI在Claude Desktop、MCPJam、VS Code和Goose中呈现。

所得

每个工具都返回一个交互式UI。13个工具，15个屏幕：

日历视图

加 日视图 （24小时时间线）， 周视图 （7列网格），以及 月视图 （带有事件药丸的日历网格）——所有这些都可以作为替代视图使用。

事件操作

公用事业

所有UI支持 亮暗模式 自动。

运作原理

You: "what's on my calendar this week?"
  → AI calls list-events tool
  → Server returns event data + ui://gcal/upcoming resource
  → Host fetches the HTML and renders it in a sandboxed iframe
  → You see an interactive calendar view inline in the chat
  → Click "Join" → opens Google Meet link
  → Click "Load more" → fetches next page of events

这 _meta.ui.resourceUri 每个工具定义中的字段告诉主机要渲染哪个UI。UI通过以下方式与服务器通信 postMessage --它可以调用任何工具（导航日期、创建事件、RSVP），而无需额外的提示。

没有MCP Apps支持的主机仍然会收到文本回复。UI是可添加的。

建筑

google-calendar-mcp-app/
├── apps/                       # 15 MCP Apps (HTML + TypeScript)
│   ├── shared/                 # Shared code
│   │   ├── gcal-app.ts         # Typed tool wrappers, theme detection
│   │   ├── components.ts       # Reusable UI components (11 components)
│   │   ├── time-utils.ts       # Date formatting, calendar math
│   │   └── theme.css           # CSS design tokens (light + dark)
│   ├── upcoming/               # Default for list-events
│   ├── day-view/               # 24h timeline
│   ├── week-view/              # 7-column grid
│   ├── month-view/             # Monthly grid
│   ├── agenda/                 # Searchable list
│   ├── event-detail/           # Event card with actions
│   ├── event-form/             # Create/edit form
│   ├── delete-confirm/         # Deletion confirmation
│   ├── rsvp-confirm/           # RSVP confirmation
│   ├── bulk-create/            # Bulk creation progress
│   ├── freebusy/               # Availability heatmap
│   ├── calendar-list/          # Calendar browser
│   ├── colors/                 # Color palette
│   ├── clock/                  # Clock / timezone
│   └── accounts/               # Account manager
├── src/                        # MCP server (TypeScript)
│   ├── server.ts               # Server entry + UI resource registration
│   ├── apps/ui-resources.ts    # Tool → UI mapping (15 resources)
│   ├── tools/registry.ts       # 13 tool definitions with _meta.ui
│   ├── handlers/core/          # Google Calendar API handlers
│   ├── auth/                   # OAuth 2.0 (multi-account)
│   ├── transports/             # Stdio + HTTP
│   └── services/               # Conflict detection, calendar registry
└── build/                      # Compiled output

Vite将每个UI捆绑到一个独立的HTML文件中。服务器将这些作为 ui:// MIME类型的资源 text/html;profile=mcp-app.

共享组件库

所有15个UI共享可重用组件 apps/shared/components.ts:

所有组件都使用CSS自定义属性——亮模式和暗模式会自动工作。

发展

npm install              # Install dependencies
npm run build            # Build everything (apps + server)
npm run build:apps       # Build 15 UI apps only
npm run build:server     # Build server only
npm test                 # Run 808 unit tests
npm run lint             # TypeScript type check

# Run locally
export GOOGLE_OAUTH_CREDENTIALS=./gcp-oauth.keys.json
npm run start:http -- --port 3001    # HTTP mode
npm start                            # Stdio mode (for Claude Desktop)

添加新UI

1. 创建 apps//index.html 和 apps//src/app.ts
2. 使用 createGCalApp() 来自共享代码+可重用组件
3. 注册于 src/apps/ui-resources.ts （添加到 UI_RESOURCES + TOOL_UI_MAP)
4. npm run build → 使用MCPJam检查器进行测试

多账户支持

连接多个Google帐户并同时查询它们：

# In chat, use the manage-accounts tool:
# "Add my work Google account"

# Or from CLI:
npm run account auth work      # Authenticate 'work' account
npm run account auth personal  # Authenticate 'personal' account

当多个帐户连接时， list-events 合并所有帐户的结果。写入操作会自动选择具有正确权限的帐户。

学分

• 日历工具： nspady/谷歌日历mcp （MIT）
• MCP应用程序协议： modelcontextprotocol/ext应用程序
• MCP-SDK： @模型上下文协议/sdk

许可证

麻省理工学院——见 许可证 了解详情。