谷歌日历 MCP 服务器

什么是 Google Calendar MCP？

Google Calendar MCP（多渠道平台）是一个集成工具，旨在增强 Google 日历中的事件管理。该工具允许用户简化调度流程，使创建、修改和管理跨多个平台的事件变得更加容易。通过 Google Calendar MCP，用户可以将日历与其他应用程序同步，确保所有与事件相关的信息都是最新的，并且可以从单一界面访问。

Google Calendar MCP 的特点

事件管理：直接从平台轻松创建、编辑和删除事件。
多渠道集成：将您的 Google 日历与其他应用程序同步，以无缝管理事件。
用户友好的界面：直观的设计简化了导航，增强了用户体验。
实时更新：接收任何对事件所做更改的即时通知和更新。
可定制设置：根据您的特定调度需求和偏好调整应用程序。

如何使用 Google Calendar MCP

安装：首先从官方库下载并安装 Google Calendar MCP 应用程序。
帐户设置：使用您的 Google 帐户登录以链接您的日历。
同步：配置同步设置以连接您用于事件管理的其他应用程序。
创建事件：使用界面创建新事件，设置提醒并邀请参与者。
管理事件：根据需要修改现有事件，并确保所有更改在所有同步平台上反映。

常见问题解答

问：Google Calendar MCP 是免费使用的吗？

答：是的，Google Calendar MCP 是免费的，允许用户在没有任何订阅费用的情况下管理他们的事件。

问：我可以将 Google Calendar MCP 与其他工具集成吗？

答：当然可以！Google Calendar MCP 旨在与各种应用程序协同工作，增强您的事件管理能力。

问：Google Calendar MCP 支持哪些平台？

答：Google Calendar MCP 支持多个平台，确保用户可以从不同设备和应用程序访问他们的日历。

问：我如何获得 Google Calendar MCP 的支持？

答：支持可以通过官方库的问题跟踪器获得，用户可以在此报告错误或寻求社区的帮助。

问：我的数据在 Google Calendar MCP 中安全吗？

答：是的，Google Calendar MCP 遵循数据安全的最佳实践，确保您的信息在同步和使用过程中受到保护。

Google Calendar MCP Server

A Model Context Protocol (MCP) server that provides Google Calendar integration for AI assistants like Claude.

Features

Multi-Calendar Support: List events from multiple calendars simultaneously
Event Management: Create, update, delete, and search calendar events
Recurring Events: Advanced modification capabilities for recurring events
Free/Busy Queries: Check availability across calendars
Smart Scheduling: Natural language understanding for dates and times
Inteligent Import: Add calendar events from images, PDFs or web links

Quick Start

Prerequisites

A Google Cloud project with the Calendar API enabled
OAuth 2.0 credentials (Desktop app type)

Google Cloud Setup

Go to the Google Cloud Console
Create a new project or select an existing one.
Enable the Google Calendar API for your project. Ensure that the right project is selected from the top bar before enabling the API.
Create OAuth 2.0 credentials:
- Go to Credentials
- Click "Create Credentials" > "OAuth client ID"
- Choose "User data" for the type of data that the app will be accessing
- Add your app name and contact information
- Add the following scopes (optional):
  - https://www.googleapis.com/auth/calendar.events and https://www.googleapis.com/auth/calendar
- Select "Desktop app" as the application type (Important!)
- Save the auth key, you'll need to add its path to the JSON in the next step
- Add your email address as a test user under the Audience screen
  - Note: it might take a few minutes for the test user to be added. The OAuth consent will not allow you to proceed until the test user has propagated.
  - Note about test mode: While an app is in test mode the auth tokens will expire after 1 week and need to be refreshed (see Re-authentication section below).

Installation

Option 1: Use with npx (Recommended)

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["@cocal/google-calendar-mcp"],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json"
      }
    }
  }
}

⚠️ Important Note for npx Users: When using npx, you must specify the credentials file path using the GOOGLE_OAUTH_CREDENTIALS environment variable.

Option 2: Local Installation

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

Then add to Claude Desktop config using the local path or by specifying the path with the GOOGLE_OAUTH_CREDENTIALS environment variable.

Option 3: Docker Installation

git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
cp /path/to/your/gcp-oauth.keys.json .
docker compose up

See the Docker deployment guide for detailed configuration options including HTTP transport mode.

First Run

Start Claude Desktop
The server will prompt for authentication on first use
Complete the OAuth flow in your browser
You're ready to use calendar features!

Re-authentication

If you're in test mode (default), tokens expire after 7 days. If you are using a client like Claude Desktop it should open up a browser window to automatically re-auth. However, if you see authentication errors you can also resolve by following these steps:

For npx users:

export GOOGLE_OAUTH_CREDENTIALS="/path/to/your/gcp-oauth.keys.json"
npx @cocal/google-calendar-mcp auth

For local installation:

npm run auth

To avoid weekly re-authentication, publish your app to production mode (without verification):

Go to Google Cloud Console → "APIs & Services" → "OAuth consent screen"
Click "PUBLISH APP" and confirm
Your tokens will no longer expire after 7 days but Google will show a more threatning warning when connecting to the app about it being unverified.

See Authentication Guide for details.

Example Usage

Along with the normal capabilities you would expect for a calendar integration you can also do really dynamic, multi-step processes like:

Cross-calendar availability:

Please provide availability looking at both my personal and work calendar for this upcoming week.
I am looking for a good time to meet with someone in London for 1 hr.

Add events from screenshots, images and other data sources:
```
Add this event to my calendar based on the attached screenshot.
```
Supported image formats: PNG, JPEG, GIF Images can contain event details like date, time, location, and description

Calendar analysis:

What events do I have coming up this week that aren't part of my usual routine?

Check attendance:

Which events tomorrow have attendees who have not accepted the invitation?

Auto coordinate events:

Here's some available that was provided to me by someone. {available times}
Take a look at the times provided and let me know which ones are open on my calendar.

Available Tools

| Tool | Description | ||-| | list-calendars | List all available calendars | | list-events | List events with date filtering | | search-events | Search events by text query | | create-event | Create new calendar events | | update-event | Update existing events | | delete-event | Delete events | | get-freebusy | Check availability across calendars, including external calendars | | list-colors | List available event colors |

Documentation

Authentication Setup - Detailed Google Cloud setup
Advanced Usage - Multi-account, batch operations
Deployment Guide - HTTP transport, remote access
Docker Guide - Docker deployment with stdio and HTTP modes
OAuth Verification - Moving from test to production mode
Architecture - Technical architecture overview
Development - Contributing and testing
Testing - Unit and integration testing guide

Configuration

Environment Variables:

GOOGLE_OAUTH_CREDENTIALS - Path to OAuth credentials file
GOOGLE_CALENDAR_MCP_TOKEN_PATH - Custom token storage location (optional)

Claude Desktop Config Location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Security

OAuth tokens are stored securely in your system's config directory
Credentials never leave your local machine
All calendar operations require explicit user consent

Troubleshooting

OAuth Credentials File Not Found:
- For npx users: You must specify the credentials file path using GOOGLE_OAUTH_CREDENTIALS
- Verify file paths are absolute and accessible
Authentication Errors:
- Ensure your credentials file contains credentials for a Desktop App type
- Verify your user email is added as a Test User in the Google Cloud OAuth Consent screen
- Try deleting saved tokens and re-authenticating
- Check that no other process is blocking ports 3000-3004
Build Errors:
- Run npm install && npm run build again
- Check Node.js version (use LTS)
- Delete the build/ directory and run npm run build
"Something went wrong" screen during browser authentication
- Perform manual authentication per the below steps
- Use a Chromium-based browser to open the authentication URL. Test app authentication may not be supported on some non-Chromium browsers.

Manual Authentication

For re-authentication or troubleshooting:

### For npx installations
export GOOGLE_OAUTH_CREDENTIALS="/path/to/your/credentials.json"
npx @cocal/google-calendar-mcp auth

### For local installations
npm run auth

License

MIT