google-calendar-mcp-app

Google Calendar with interactive UI — right inside your AI chat.

Ask your AI assistant about your schedule and get real, interactive calendar views instead of plain text. Create events with a form. See your availability as a visual heatmap. All rendered inline in the conversation.

Built on MCP Apps, the official protocol extension for interactive UIs in AI chat. Fork of nspady/google-calendar-mcp (MIT) — all 13 calendar tools preserved, 15 interactive UI screens added on top.

Quick Start

1. Clone & Install

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

2. Set Up Google Calendar Access

You need OAuth credentials to access the Google Calendar API. Two ways to set this up:

Option A: Using gcloud CLI (fastest)

If you have Google Cloud CLI installed:

# 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

Then finish in the browser (2 clicks):

1. Configure consent screen — open OAuth consent screen, pick "External", fill app name + your email, skip scopes, add yourself as test user
2. Create credentials — open Create OAuth client, select "Desktop app", create, download JSON

Save the downloaded file as gcp-oauth.keys.json in the project root.

Option B: All in browser

1. Go to Google Cloud Console → create a project
2. Search "Google Calendar API" → Enable it
3. Go to APIs & Services → OAuth consent screen → External → fill basics → add yourself as test user
4. Go to Credentials → Create Credentials → OAuth client ID → Desktop app → Download JSON
5. Save as gcp-oauth.keys.json in the project root

3. Authenticate

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

A browser window opens — sign in with your Google account and grant calendar access. Tokens are saved locally. You only need to do this once (tokens auto-refresh).

Tip: If you see "This app isn't verified", click Advanced → Go to [app name] (unsafe). This is normal for test-mode apps.

4. Connect to Your AI Host

Claude Desktop (recommended — full MCP Apps UI support)

Add to ~/.config/Claude/claude_desktop_config.json (Linux) or ~/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"
      }
    }
  }
}

Restart Claude Desktop. Ask: "What's on my calendar this week?"

MCPJam Inspector (best for testing & development)

# 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

Open http://localhost:6274, click Add Server → HTTP, enter http://127.0.0.1:3001, connect. Select any tool and call it — the interactive UI renders inline.

VS Code (GitHub Copilot)

VS Code with GitHub Copilot supports MCP Apps. Add the server in VS Code's MCP settings and use Copilot Chat.

Claude.ai (web — text only, no UI rendering)

# 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

Note: Claude.ai web currently shows text responses only. Interactive UIs render in Claude Desktop, MCPJam, VS Code, and Goose.

What You Get

Every tool returns an interactive UI. 13 tools, 15 screens:

Calendar Views

| When you ask... | You see | |----------------|---------| | "Show my calendar" | Upcoming Events — events grouped by day, colored cards with time/title/location | | "Search for meetings" | Agenda — searchable list with date filters and keyboard navigation | | "Am I free Thursday?" | Availability — visual free/busy heatmap across all your calendars |

Plus Day View (24h timeline), Week View (7-column grid), and Month View (calendar grid with event pills) — all available as alternate views.

Event Actions

| When you ask... | You see | |----------------|---------| | "Show me the team meeting details" | Event Detail — attendees, RSVP status, Join Meeting button, location map, delete action | | "Create a meeting tomorrow at 2pm" | Event Form — title, date/time pickers, calendar selector, color picker, attendee chips | | "Delete the standup" | Delete Confirmation — animated success/error card | | "Accept the Friday invite" | RSVP Confirmation — response status with event summary | | "Add these 10 events" | Bulk Progress — progress bar with per-event success/failure |

Utilities

| When you ask... | You see | |----------------|---------| | "List my calendars" | Calendar List — color swatches, access roles, grouped by account | | "Show available colors" | Color Palette — event/calendar colors with names, click to copy ID | | "What time is it?" | Clock — digital clock with timezone, DST indicator, auto-updating | | "Show connected accounts" | Account Manager — status badges, calendar counts, auth management |

All UIs support light and dark mode automatically.

How It Works

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

The _meta.ui.resourceUri field in each tool definition tells the host which UI to render. The UI communicates back to the server via postMessage — it can call any tool (navigate dates, create events, RSVP) without additional prompts.

Hosts without MCP Apps support still get text responses. The UI is additive.

Architecture

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

Each UI is bundled by Vite into a single self-contained HTML file. The server serves these as ui:// resources with MIME type text/html;profile=mcp-app.

Shared Component Library

All 15 UIs share reusable components at apps/shared/components.ts:

| Component | Use | |-----------|-----| | renderEventCard() | Event card with color bar, time, title | | renderAttendeeChip() | Avatar + name + RSVP status | | renderBadge() | Status badges (success/error/warning/info) | | renderButton() | Themed buttons (primary/secondary/danger) | | renderListItem() | List row with icon + title + badge | | showToast() | Notification popup | | showConfirmDialog() | Confirm/cancel modal | | renderSpinner() | Loading state | | renderEmptyState() | Placeholder with icon |

All components use CSS custom properties — light and dark mode work automatically.

Development

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)

Adding a New UI

1. Create apps/<name>/index.html and apps/<name>/src/app.ts
2. Use createGCalApp() from shared code + reusable components
3. Register in src/apps/ui-resources.ts (add to UI_RESOURCES + TOOL_UI_MAP)
4. npm run build → test with MCPJam Inspector

Multi-Account Support

Connect multiple Google accounts and query them simultaneously:

# 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

When multiple accounts are connected, list-events merges results from all accounts. Write operations auto-select the account with the right permissions.

Credits

• Calendar tools: nspady/google-calendar-mcp (MIT)
• MCP Apps protocol: modelcontextprotocol/ext-apps
• MCP SDK: @modelcontextprotocol/sdk

License

MIT — see LICENSE for details.