使用说明

谷歌日历MCP服务器

一个基于TypeScript的模型上下文协议（MCP）服务器，允许Claude Desktop连接到谷歌日历并与之交互。

特性

将Claude Desktop AI连接到谷歌日历数据
使用Google OAuth2进行授权
检索日历列表和事件
创建、更新和删除日历事件
获取所有日历中即将发生的事件
安全令牌处理
具有强类型的TypeScript

需求

Node.js（v16或更高版本）
npm或纱线
具有日历访问权限的Google帐户
Google OAuth2凭据（用于Cloud OAuth方法）

安装

1.克隆存储库

git clone https://github.com/Jackson88/google-calendar-mcp
cd google-calendar-mcp

2.安装依赖项

npm install
# or
yarn install

3.配置环境变量

创建一个 .env 文件基于 .env.example:

cp .env.example .env

然后编辑 .env 使用您的配置文件：

# Authentication Method Configuration
# -----------------------------
# Two authentication methods are available:
# 1. google_cloud - Uses Google Cloud OAuth (requires Google Cloud project setup)
# 2. direct - Uses direct authentication (simpler, doesn't require Google Cloud project)

# Choose one of the following authentication methods:
# AUTH_METHOD=google_cloud
AUTH_METHOD=direct

# Server Configuration
# -------------------
PORT=3000
NODE_ENV=development

# Google Calendar API (required only if AUTH_METHOD=google_cloud)
# --------------------------------------------------------------
# These credentials require a Google Cloud Platform project with Google Calendar API enabled
# You'll need to create OAuth credentials and configure the redirect URI in Google Cloud Console
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback

# MCP Configuration
# ----------------
MCP_SERVER_ID=google-calendar-mcp
MCP_SERVER_NAME=Google Calendar Integration
MCP_SERVER_DESCRIPTION=Retrieves and manages Google Calendar events

身份验证方法

此MCP服务器支持两种身份验证方法：

1.谷歌云OAuth（推荐）

这是推荐和最安全的方法。它需要创建Google Cloud项目和OAuth凭据，但提供了最佳的安全性和用户体验。

遵循OAuth 2.0最佳实践
不直接处理用户凭据
生产使用最可靠

要设置Google Cloud OAuth，请执行以下操作：

转到谷歌云控制台
创建新项目
启用Google日历API
创建OAuth2凭据（Web应用程序类型）
添加授权重定向URI：
- 发展： http://localhost:3000/auth/callback
- 用于生产：您的生产回调URL

2.直接身份验证（简化）

对于个人或开发用途，您可以使用不需要Google Cloud设置的简化直接身份验证方法。

使用直接Google帐户身份验证
设置更简单，但存在安全性和可靠性限制
最适合个人或发展用途

要使用直接身份验证，请在您的 .env 文件：

AUTH_METHOD=direct

注意：直接身份验证可能受谷歌安全政策的约束，如果谷歌更改其身份验证要求，可能会停止工作。

运行服务器

开发模式

# Start the development server with hot reloading
npm run dev
# or
yarn dev

生产模式

# Build the TypeScript code
npm run build
# or
yarn build

# Start the production server
npm run start
# or
yarn start

为MCP集成配置Claude

关于Claude兼容性的重要说明

⚠️ 当前限制：截至2025年4月，Claude Desktop可能对MCP连接的支持有限或没有支持。测试表明，无论使用何种身份验证方法，当前版本的Claude Desktop都无法连接到外部MCP服务器。以下说明仅供将来在Claude Desktop完全支持MCP服务器连接时参考。

如果您收到一条错误消息，指出“我无法连接到任何外部服务器”，则表示您的Claude Desktop版本当前不支持外部MCP连接。这是当前Claude Desktop实现的限制，而不是此MCP服务器的问题。

先决条件

您必须在计算机上安装Claude Desktop
Google日历MCP服务器必须正在运行且可访问
您的Claude Desktop版本必须支持MCP连接

运行服务器

您需要手动启动MCP服务器之前要求Claude连接到它。Claude Desktop不会使用npx或任何其他命令为您运行服务器。

按照以下步骤设置集成：

启动MCP服务器：

# Development mode
npm run dev

# OR Production mode (after building)
npm run build
npm run start

使用Google进行身份验证（仅限第一次）：
- 对于Google Cloud OAuth：请访问http://localhost:3000/mcp/auth/url在浏览器中完成授权流程
- 对于直接身份验证：使用Postman或curl等工具向以下对象发送POST请求http://localhost:3000/auth/direct使用您的凭据

直接身份验证方法

此服务器支持Google日历的两种身份验证方法。两者都可以直接与服务器API一起使用，即使Claude Desktop连接还不受支持。

1.谷歌云OAuth（推荐）

这是使用标准OAuth流的更安全的方法：

访问http://localhost:3000/mcp/auth/url在浏览器中
完成谷歌授权流程
您将被重定向回回调URL

2.直接身份验证

对于未设置Google Cloud的开发/测试：

# Using curl
curl -X POST http://localhost:3000/auth/direct \
  -H "Content-Type: application/json" \
  -d '{"email":"your.email@gmail.com","password":"your_password"}'  

# Or with cookies
curl -X POST http://localhost:3000/auth/direct \
  -H "Content-Type: application/json" \
  -d '{"cookies":"your_google_cookies"}'

这些方法允许您直接测试服务器功能，即使尚不支持Claude Desktop连接。

配置Claude桌面设置

Claude Desktop需要配置为识别和访问您的MCP服务器：

找到您的Claude Desktop设置文件：
- 在macOS上： ~/Library/Application Support/Claude/claude_desktop_config.json
- 在Windows上： %APPDATA%\Claude\claude_desktop_config.json

将MCP服务器配置添加到设置文件中：

在文本编辑器中打开settings.json文件
查找或创建 mcpServers 章节
添加以下配置（根据需要进行调整）：

 {
   "mcpServers": {
     "google-calendar": {
       "command": "npx",
       "args": ["-y", "google-calendar-mcp"],
       "env": {
         "GOOGLE_CLIENT_ID": "<your-client-id>",
         "GOOGLE_CLIENT_SECRET": "<your-client-secret>",
         "GOOGLE_REDIRECT_URI": "http://localhost:3000/auth/callback"
       },
       "description": "Google Calendar MCP server using npx"
     }
   }
 }

保存文件并重新启动Claude Desktop

注意：此方法需要手动编辑配置文件，应谨慎使用。在进行更改之前，始终备份设置文件。

验证连接

问克劳德一个简单的日历相关问题，比如“我今天有什么活动？”
如果它以您的日历信息作为响应，则表示连接正常

克劳德连接故障排除

如果Claude无法连接到您的MCP服务器：

查看克劳德的回复： 克劳德通常会告诉你连接是否有问题
验证服务器URL: 确保您指定了正确的URL，包括/mcp路径
检查服务器日志： 查看运行MCP服务器的控制台是否有任何错误消息
重新启动两个应用程序： 有时重新启动Claude Desktop和MCP服务器可以解决连接问题
身份验证状态： 在尝试使用连接之前，请确保您已成功通过Google的身份验证
联系Anthropic支持： 如果您收到Claude无法连接到外部服务器的消息，您可能需要联系Anthropic支持，了解您版本的Claude Desktop的MCP功能可用性

克劳德命令参考

连接后，您可以要求Claude执行各种日历操作：

# View your schedule
What events do I have today?
What's on my calendar for next week?
Show me my meetings for tomorrow afternoon.

# Create events
Schedule a team meeting next Monday at 10 AM for 1 hour.
Add a doctor's appointment on Friday at 2 PM.
Create a recurring weekly check-in every Wednesday at 9 AM.

# Modify events
Reschedule my 3 PM meeting to 4 PM.
Move tomorrow's lunch meeting to Thursday.
Cancel my dentist appointment.

# Find available times
When am I free tomorrow for a 2-hour meeting?
Do I have any conflicts next Tuesday morning?
Find me an open 30-minute slot this week for a quick call.

测试

# Run tests
npm test
# or
yarn test

API终点

服务器公开以下MCP端点：

认证

GET /mcp/auth/url -获取Google OAuth2授权URL
POST /mcp/auth/callback -授权后处理OAuth2回调
POST /auth/direct -使用Google帐户进行直接身份验证（使用直接身份验证方法时）

日历

GET /mcp/calendars -获取可用日历列表

事件

GET /mcp/events -从特定日历中获取事件
GET /mcp/events/upcoming -获取所有日历中即将发生的事件
POST /mcp/events/create -创建新的日历事件
PUT /mcp/events/update -更新现有日历事件
DELETE /mcp/events/delete -删除日历事件
GET /mcp/events/detail -获取特定事件的详细信息

察看连接信息

GET /mcp/info -获取服务器信息和可用端点
GET /health -健康检查端点

Claude Desktop使用示例

以下是一些如何将此MCP服务器与Claude Desktop一起使用的示例：

1.了解即将发生的事件

Claude, what are my upcoming calendar events for the next week?

Claude将查询MCP服务器并返回您即将发生的事件列表。

2.创建新事件

Claude, please schedule a meeting with John Doe about the project proposal for tomorrow at 2:00 PM, lasting for 1 hour.

Claude将根据您的请求创建一个新的日历事件。

3.发现日程安排中的冲突

Claude, do I have any scheduling conflicts next Monday between 10 AM and 3 PM?

克劳德将检查您的日历，并通知您任何现有的事件。

4.重新安排活动

Claude, I need to reschedule my doctor's appointment on Thursday to Friday at the same time.

Claude将定位事件并用新日期更新。

5.安排定期会议

Claude, please create a weekly team standup meeting every Monday at 9:00 AM starting next week.

Claude将创建一个重复的日历事件。

6.寻找空闲时间

Claude, when am I free for a 2-hour meeting with the design team this week?

克劳德会分析你的日历，并建议可用的时间段。

Docker部署

该项目包括Docker配置，便于部署：

# Build and run with Docker Compose
docker-compose up -d

安全考虑

此MCP服务器在文件中本地存储身份验证令牌。确保这些文件是安全的，并且不受版本控制。
在生产环境中，考虑实施更安全的令牌存储方法。
默认情况下，服务器在生产模式下使用HTTPS进行安全通信。
令牌到期时，会自动处理令牌刷新。

故障排除

身份验证问题

如果遇到身份验证问题：

确保您的凭据在中配置正确 .env 文件
检查重定向URI是否与Google Cloud Console中配置的完全匹配（适用于Cloud OAuth）
确保在您的Google Cloud项目中启用Google Calendar API（用于Cloud OAuth）
尝试清除令牌文件并重新进行身份验证

连接问题

如果Claude Desktop无法连接到MCP服务器：

验证服务器是否正在运行，并且可以在指定的URL上访问
检查防火墙设置以确保端口打开
确保服务器的端口与Claude Desktop尝试连接的端口匹配

日历访问问题

如果您在访问日历或活动时遇到问题：

确保您在身份验证流程中授予了必要的权限
检查您的Google帐户是否可以访问您尝试查看的日历
验证所使用的日历ID是否正确

贡献

欢迎投稿！请随时提交拉取请求。

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

使用说明

谷歌日历MCP服务器

特性

需求

安装

1.克隆存储库

2.安装依赖项

3.配置环境变量

身份验证方法

1.谷歌云OAuth（推荐）

2.直接身份验证（简化）

运行服务器

开发模式

生产模式

为MCP集成配置Claude

关于Claude兼容性的重要说明

先决条件

运行服务器

直接身份验证方法

1.谷歌云OAuth（推荐）

2.直接身份验证

配置Claude桌面设置

验证连接

克劳德连接故障排除

克劳德命令参考

测试

API终点

认证

日历

事件

察看连接信息

Claude Desktop使用示例

1.了解即将发生的事件

2.创建新事件

3.发现日程安排中的冲突

4.重新安排活动

5.安排定期会议

6.寻找空闲时间

Docker部署

安全考虑

故障排除

身份验证问题

连接问题

日历访问问题

贡献

许可证

相关 MCP

小红书MCP服务

Figma MCP集成工具

MCP 协议测试服务器

Flomo笔记服务

Unity编辑器AI集成插件

科学研究的开源MCP服务器