🔔 版本更新通知 🔔
1.0.5 版本新增了对重复事件的支持，通过createEvent和updateEvent工具中的recurrence参数即可实现。这样一来，您可以直接创建和修改重复事件，而无需在创建后手动设置。
Google 日历 MCP 服务器是一个 MCP（模型上下文协议）服务器实现，可实现 Google 日历与 Claude 桌面的集成。该项目使 Claude 能够与用户的 Google 日历进行交互，并通过自然语言交互提供显示、创建、更新和删除日历事件的功能。
Google 日历集成：在 Claude Desktop 和 Google 日历 API 之间架起桥梁
MCP 实现：遵循模型上下文协议规范，用于 AI 辅助工具集成
OAuth2 身份验证：安全地处理 Google API 身份验证流程
事件管理：支持全面的日历事件操作（获取、创建、更新、删除）
颜色支持：能够使用 colorId 参数设置和更新事件颜色
STDIO 传输：使用标准输入/输出与 Claude Desktop 进行通信
Related MCP server: calendar-mcp
该项目使用：
TypeScript ：用于类型安全的代码开发
MCP SDK ：使用@modelcontextprotocol/sdk与Claude Desktop集成
Google API ：使用googleapis访问 Google 日历 API
Zod ：实现请求/响应数据的模式验证
基于环境的配置：使用 dotenv 进行配置管理
Helmet.js ：用于安全标头
AES-256-GCM ：用于令牌加密
Jest ：用于单元测试和覆盖率
GitHub Actions ：用于 CI/CD
MCP 服务器：处理与 Claude Desktop 通信的核心服务器实现
Google 日历工具：日历操作（检索、创建、更新、删除）
身份验证处理程序：使用 Google API 管理 OAuth2 流程
模式验证：确保所有操作中的数据完整性
令牌管理器：安全处理身份验证令牌
此 MCP 服务器提供以下与 Google 日历交互的工具：
使用各种过滤选项检索日历事件。
参数：
calendarId （可选）：日历 ID（如果省略则使用主日历）
timeMin （可选）：事件检索的开始时间（ISO 8601 格式，例如“2025-03-01T00:00:00Z”）
timeMax （可选）：事件检索的结束时间（ISO 8601 格式）
maxResults （可选）：要检索的最大事件数（默认值：10）
orderBy （可选）：排序顺序（“startTime”或“updated”）
创建一个新的日历事件。
参数：
calendarId （可选）：日历 ID（如果省略则使用主日历）
event ：事件详细信息对象，包含：
summary （必填）：活动标题
description （可选）：事件描述
location （可选）：活动地点
start ：开始时间对象：
dateTime （可选）：ISO 8601 格式（例如，“2025-03-15T09：00：00 + 09：00”）
date （可选）：全天活动的格式为 YYYY-MM-DD
timeZone （可选）：时区（例如“亚洲/东京”）
end ：结束时间对象（与开始格式相同）
attendees （可选）：带有电子邮件和可选显示名称的与会者数组
colorId （可选）：事件颜色ID（1-11）
recurrence （可选）：RFC5545 格式的重复规则数组（例如，[“RRULE：FREQ=WEEKLY;BYDAY=MO,WE,FR”]）
更新现有日历事件。该函数首先获取现有事件数据，然后将其与更新数据合并，并保留更新请求中未包含的字段。
参数：
calendarId （可选）：日历 ID（如果省略则使用主日历）
eventId （必需）：要更新的事件的 ID
event ：包含要更新的字段的事件详细信息对象（与 createEvent 相同的结构，所有字段都是可选的）
只有明确提供的字段才会更新
更新请求中未包含的字段将保留其现有值
这允许部分更新而不会丢失数据
可以更新recurrence参数来修改重复事件模式
删除日历事件。
参数：
calendarId （可选）：日历 ID（如果省略则使用主日历）
eventId （必需）：要删除的事件的 ID
使用 Google 日历重新验证身份。当您想在不同的 Google 帐户之间切换而无需重启 Claude 时，此功能非常有用。
参数：
没有任何
添加新功能、修改代码或修复错误时，请使用npm version命令语义化地增加每次更改的版本号。此外，请确保您的代码清晰易懂，并遵循所有必要的编码规则，例如面向对象编程 (OOP)。版本脚本会在版本更新时自动运行npm install ，但您仍应在提交代码之前构建、运行 lint 并测试代码。
src/ ：源代码目录
auth/ ：身份验证处理
config/ ：配置设置
mcp/ ：MCP 服务器实现
tools/ ：Google 日历工具实现
utils/ ：实用函数和助手
根据 TypeScript 最佳实践进行正确输入
维护全面的错误处理
确保正确的身份验证流程
保持依赖项最新
为所有功能编写清晰的文档
实施安全最佳实践
遵循 OAuth 2.1 身份验证标准
对所有输入/输出数据使用架构验证
实施核心功能的单元测试
彻底测试身份验证流程
验证针对 Google API 的日历操作
使用覆盖率报告运行测试
确保包含安全测试
该软件包在 npm 上发布为@takumi0706/google-calendar-mcp ：
npx @takumi0706/google-calendar-mcp@1.0.5创建 Google Cloud 项目并启用 Google 日历 API
在 Google Cloud Console 中配置 OAuth2 凭据
设置环境变量：
# Create a .env file with your Google OAuth credentials
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:4153/oauth2callback
# Optional: Token encryption key (auto-generated if not provided)
TOKEN_ENCRYPTION_KEY=32-byte-hex-key
# Optional: Auth server port and host (default port: 4153, host: localhost)
AUTH_PORT=4153
AUTH_HOST=localhost
# Optional: MCP server port and host (default port: 3000, host: localhost)
PORT=3000
HOST=localhost
# Optional: Enable manual authentication (useful when localhost is not accessible)
USE_MANUAL_AUTH=true将服务器添加到claude_desktop_config.json文件中。如果您在无法访问 localhost 的环境中运行，请将USE_MANUAL_AUTH环境变量设置为“true”。
{
"mcpServers": {
"google-calendar": {
"command": "npx",
"args": [
"-y",
"@takumi0706/google-calendar-mcp"
],
"env": {
"GOOGLE_CLIENT_ID": "your_client_id",
"GOOGLE_CLIENT_SECRET": "your_client_secret",
"GOOGLE_REDIRECT_URI": "http://localhost:4153/oauth2callback"
}
}
}
}OAuth 令牌仅存储在内存中（不存储在基于文件的存储中）
敏感凭据必须作为环境变量提供
使用 AES-256-GCM 进行令牌加密以实现安全存储
具有显式 code_verifier 和 code_challenge 生成的PKCE 实现
状态参数验证以进行 CSRF 保护
使用 Helmet.js 应用的安全标头
API 端点保护的速率限制
使用 Zod 模式进行输入验证
有关更多详细信息，请参阅SECURITY.md 。
定期更新以保持与 Google 日历 API 的兼容性
版本更新记录在 README.md 中
如果您遇到任何问题：
确保您的 Google OAuth 凭据已正确配置
确保您拥有足够的权限来访问 Google 日历 API
验证您的 Claude Desktop 配置是否正确
JSON 解析错误：如果您看到类似Unexpected non-whitespace character after JSON at position 4 (line 1 column 5)之类的错误，通常是由于 JSON-RPC 消息格式错误造成的。此问题已在 0.6.7 及更高版本中修复。如果您仍然遇到这些错误，请更新到最新版本。
身份验证错误：验证您的 Google OAuth 凭据
状态参数无效：如果您在重新Authentication failed: Invalid state parameter ，请更新至 1.0.3 或更高版本，该版本已修复 OAuth 服务器生命周期管理问题。在旧版本中，您可能需要关闭 4153 端口并重启应用程序。
连接错误：确保只有一个服务器实例正在运行
断开连接问题：确保您的服务器在没有自定义 TCP 套接字的情况下正确处理 MCP 消息
无法访问 localhost ：如果您在无法访问 localhost 的环境中运行应用程序（例如远程服务器或容器），请通过设置USE_MANUAL_AUTH=true启用手动身份验证。这将允许您在授权应用程序后手动输入 Google 显示的授权码。
修复了此 google 日历 mcp 服务器中不需要范围的问题
通过createEvent和updateEvent工具中的recurrence参数添加了对重复事件的支持
允许直接创建和修改重复事件，无需手动设置
维护版本，版本号更新
与 1.0.3 版相比没有功能变化
确保与最新依赖项的兼容性
添加了新的authenticate工具，允许在不重新启动 Claude 的情况下重新进行身份验证
可以在会话期间切换不同的 Google 帐户
通过 MCP 接口公开身份验证功能
无需重新启动即可切换帐户，从而增强用户体验
为无法访问 localhost 的环境添加了手动身份验证选项
实现了 readline 接口，用于手动输入授权码
添加了 USE_MANUAL_AUTH 环境变量以启用手动身份验证
将 zod 依赖项更新至最新版本（3.24.2）
使用最新的 zod 功能改进了架构验证
增强代码稳定性和安全性
修复重新认证期间的“无效状态参数”错误
修改 OAuth 服务器以按需启动并在身份验证后关闭
改进服务器生命周期管理以防止端口冲突
增强身份验证流程的错误处理
修复了updateEvent函数以在执行部分更新时保留现有事件数据
添加了getEvent函数，用于在更新之前获取现有事件数据
修改updateEvent ，将更新数据与现有数据合并，以防止数据丢失
更新了架构验证，使更新请求中的所有字段都可选
改进了updateEvent函数的文档
修复了与 Node.js v20.9.0+ 和“open”包（v10+）的兼容性问题
将仅限 ESM 的“开放”包的静态导入替换为动态导入
改进了 OAuth 身份验证期间打开浏览器的错误处理
增强代码注释以提高可维护性
主要版本发布标志着生产准备就绪
全面重构代码以提高可维护性
所有消息和评论的国际化（日语翻译成英语）
增强代码一致性和可读性
改进错误消息以获得更好的用户体验
更新文档以反映项目的当前状态
整个代码库的标准化编码风格
增强 OAuth 身份验证流程以处理刷新令牌问题
添加了prompt: 'consent'参数，强制 Google 显示同意屏幕并提供新的刷新令牌
修改身份验证流程，如果刷新令牌不可用，则仅使用访问令牌
改进了令牌刷新逻辑，以处理没有刷新令牌或刷新令牌无效的情况
更新了令牌存储以保存刷新的访问令牌，从而实现更好的令牌管理
修复了令牌刷新逻辑中潜在的无限循环
为该项目做出贡献：
# Clone the repository
git clone https://github.com/takumi0706/google-calendar-mcp.git
cd google-calendar-mcp
# Install dependencies
npm install
# Run in development mode
npm run dev运行测试：
# Run all tests
npm test
# Run tests with coverage report
npm test -- --coverage麻省理工学院
Start the Google Calendar OAuth flow. Opens a browser window for consent and stores the resulting tokens in memory.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It goes beyond the name by disclosing the browser consent behavior and that tokens are stored in memory, which implies they are not persisted across sessions. It does not cover failure modes or re-authentication, but it is meaningfully transparent for a zero-parameter tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. The action, side effect, and storage behavior are all included in minimal space, and the purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter OAuth tool with no output schema, the description covers the purpose, the user-facing behavior, and the outcome (tokens in memory). An agent has enough information to invoke the tool and understand its effect; nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the schema is trivially complete. The description adds nothing about parameters, but none are needed; the baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Start the Google Calendar OAuth flow') and gives concrete behavioral details: it opens a browser window for consent and stores tokens in memory. This clearly distinguishes it from the event-related sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear this is the authentication step for Google Calendar, which an agent can infer should precede getEvents, createEvent, and other calendar operations. It does not explicitly articulate when not to use it, but the context is unambiguous enough for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an event on a Google Calendar. Supports all-day events, attendees, reminders and RFC5545 recurrence rules.
| Name | Required | Description | Default |
|---|---|---|---|
| event | Yes | ||
| calendarId | No | primary |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It lists supported features but does not mention whether attendee invitations are sent, whether authentication is required, what the created event response looks like, or whether creation is reversible. 'Create' implies mutation, but little else is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence with no filler. It front-loads the action and resource, then packs the key capability details into a short supporting clause. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the nested event schema, the absence of annotations, and no output schema, this short description leaves important operational gaps: authentication prerequisites, default calendar behavior, return shape, and side effects like attendee emails. The feature list is helpful but insufficient for safe, confident invocation of a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is reported as 0%, and the event object is large and nested. The description partially compensates by calling out all-day events, attendees, reminders, and RFC5545 recurrence rules, which map to schema properties. Still, it does not explain the required summary/start/end fields, the calendarId default of 'primary', or the overall structure of the event object.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair: 'Create an event on a Google Calendar.' It also names supported features, which clarifies scope. This is clearly distinct from the sibling tools getEvents, updateEvent, deleteEvent, and authenticate without any ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The imperative 'Create an event' provides clear, unambiguous context for when to use the tool. However, it gives no explicit exclusion like 'use updateEvent to modify an existing event' or 'call authenticate first,' so it stops short of fully explicit routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an event from a Google Calendar by its event ID.
| Name | Required | Description | Default |
|---|---|---|---|
| eventId | Yes | ||
| calendarId | No | primary |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. While 'Delete' clearly implies a destructive mutation, it does not state whether the operation is permanent, whether confirmation or special permissions are required, or what side effects occur (e.g., removal from attendee calendars). The description is too thin to adequately characterize the risk.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It conveys the core action and key parameter efficiently, though it sacrifices some essential detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no annotations, no output schema, and 0% schema coverage, this description is insufficient. It does not cover the optional calendarId, authentication or permission expectations, undoing behavior, or any failure/response semantics. An agent cannot confidently invoke this tool correctly based on this definition alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining parameters. It does identify eventId as the core identifier, but it completely omits calendarId, which is a parameter in the schema with a default of 'primary'. The vague phrase 'Google Calendar' doesn't clarify how the calendar is selected, leaving an agent uncertain about the optional parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete'), a resource ('an event'), and a unique identifier ('event ID'), which clearly distinguishes this from siblings like createEvent, getEvents, and updateEvent. It unambiguously states the operation and object.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that the tool is used to delete an event, but provides no guidance on when this tool should be used over alternatives, no prerequisites (e.g., authentication), and no exclusions. It does not mention that calendarId is optional or defaulted, nor when a deletion might fail.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List events from a Google Calendar within an optional time range.
| Name | Required | Description | Default |
|---|---|---|---|
| orderBy | No | Sort order for the returned events | |
| timeMax | No | Upper bound (exclusive) for an event's start time, in ISO 8601 format | |
| timeMin | No | Lower bound (inclusive) for an event's end time, in ISO 8601 format | |
| calendarId | No | Calendar ID (uses the primary calendar if omitted or empty) | |
| maxResults | No | Maximum number of events to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. 'List' conveys a read-only, non-destructive operation and the time-range clause provides useful scoping, but the description omits any mention of auth needs, pagination behavior, or what happens with invalid calendar IDs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. Every word contributes to identifying the action, resource, and optional scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward list operation with a fully described schema, the description is minimally sufficient. It lacks an explicit statement about auth requirements and return shape, but the sibling set and parameter documentation provide enough context to avoid gross misuse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All five parameters are already documented in the schema (100% coverage), so the baseline applies. The description adds no parameter-level detail beyond noting the time range is optional, which is already encoded by the nullable timeMin/timeMax fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact action ('List'), the resource ('events from a Google Calendar'), and the optional time-range scope. This clearly differentiates it from the sibling mutation tools (createEvent, updateEvent, deleteEvent) and authenticate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the read/query tool for calendar events, and the sibling names make the contrast obvious. However, it does not explicitly state when to prefer it over alternatives, nor does it mention prerequisites such as authentication or calendar ownership.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing Google Calendar event. Omitted fields keep their current values.
| Name | Required | Description | Default |
|---|---|---|---|
| event | Yes | ||
| eventId | Yes | ||
| calendarId | No | primary |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It usefully states partial-update semantics ('Omitted fields keep their current values'), but it does not mention side effects, permissions, or the irreversibility of the update. A 3 reflects that it adds some valuable behavior context while leaving significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff; the purpose is front-loaded and the second sentence adds essential behavioral nuance about field omission. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested event object with complex date/reminder/recurrence schemas and no output schema or annotations, the description is too sparse. It omits how the update interacts with required fields, what happens to attendees on date changes, and any authentication or error behavior. An agent needs more context to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for explaining eventId, event, and calendarId. It only generically refers to 'fields' and the partial-update behavior, giving no specific meaning for the parameters. It fails to clarify what eventId identifies or how calendarId scopes the operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Update') and resource ('existing Google Calendar event'), which clearly differentiates it from siblings like createEvent and deleteEvent. The phrase 'existing' signals that it modifies rather than creates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for updating existing events by contrasting with creating, but it does not explicitly state when to prefer this tool over siblings, nor any exclusions. An agent can infer the use case from 'existing,' but no direct guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.0.0authenticatecreateEventdeleteEventgetEventsupdateEventScored across 5 tools
Each tool targets a distinct action on calendar events—listing, creating, updating, deleting—plus a separate authentication flow. There is no overlap or ambiguity between the tools.
Four tools follow a clear verb+Event pattern (getEvents, createEvent, updateEvent, deleteEvent), while authenticate is a necessary but non-parallel exception. Overall the naming is predictable and easy to infer.
Five tools is a well-scoped set for a Google Calendar event server: authentication plus full CRUD operations. Each tool serves a clear purpose without unnecessary bloat.
The server covers the full event lifecycle—list, create, update, delete—and includes OAuth authentication as a prerequisite. There are no obvious dead ends or critical missing operations for managing calendar events.
Hosted Google Calendar MCP server for AI agents. No self-hosting or Google Cloud setup.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A MCP server that works with Google Calendar to manage event listing, reading, and updates.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
