日历事件查询服务

MCP服务器示例-谷歌日历集成

模型上下文协议 （MCP） 服务器，可与 Google Calendar API 集成，以按日期查找和返回日历事件。

📋 索引

• 关于项目
• 功能
• 先决条件
• 安装
• 配置
• 使用
• Cursor 集成
• 项目结构
• 依赖关系
• 可用脚本
• API和工具
• 例子
• 故障排除
• 贡献
• 许可证

🎯 关于项目

该项目实现了一个MCP服务器，允许通过模型上下文协议访问谷歌日历数据。服务器提供了一个工具 （getMyCalendarDataByDate搜索特定日期的日历事件，自动过滤与“首页”相关的事件，并返回格式化的会议列表。

✨ 功能

• 按数据搜索事件将特定日历中的所有事件恢复到给定日期
• 自动过滤器自动删除标题中包含“Home”的事件
• 数据格式返回标题和开始时间格式化的事件
• 输入验证: 使用 Zod 校验日期格式
• 错误处理: 在发生故障时返回结构化错误消息

🔧 先决条件

在开始之前，请确保您已安装：

• Node.js （版本 18 或更高）
• npm 哦 纱线
• 使用 Google Calendar API 的 Google 帐户
• Google API 公钥（Public API Key）
• 您想要访问的日历 ID

📦 安装

1. 克隆仓库或导航到项目目录：

cd mcp-server-example

2. 安装依赖关系 ：

npm install

⚙️ 配置

1. 获取Google凭据

1. 访问 谷歌云控制台
2. 创建新工程或选择现有工程
3. Ative a 谷歌日历API 为您的项目
4. 去 凭据 并创建一个 API 密钥 （API密钥）
5. 复制生成的 API 密钥

2. 获取日历ID

日历ID是您的Google电子邮件

3. 设置环境变量

创建文件 .env 在项目根中，使用以下变量：

GOOGLE_PUBLIC_API_KEY=sua_chave_api_aqui
CALENDAR_ID=seu_email_google

🚀 使用

运行服务器

启动 MCP 服务器：

npm start

或者在开发模式（带手表）：

npm run dev

如何运作

MCP 服务器通过 stdio（默认输入/输出）运行，并等待 MCP 客户端的请求。他展示了工具。 getMyCalendarDataByDate 可以通过兼容的 MCP 客户端调用。

🎨 Cursor 集成

打开 MCP 配置文件并添加以下配置：

{
  "mcpServers": {
    "mcp-server-example": {
      "command": "npx",
      "args": [
       "tsx",
        "/caminho/absoluto/para/o/projeto/index.ts"
      ],
      "env": {
        "GOOGLE_PUBLIC_API_KEY": "sua_chave_api_aqui",
        "CALENDAR_ID": "seu_email_google"
      }
    }
  }
}

保存配置文件后，请完全重新启动光标以使更改生效。

📁 项目结构

mcp-server-example/
├── index.ts              # Arquivo principal do servidor MCP
├── package.json          # Dependências e scripts do projeto
├── package-lock.json     # Lock file das dependências
├── .env                  # Variáveis de ambiente (não versionado)
├── .env.example          # Exemplo de variáveis de ambiente
├── .gitignore           # Arquivos ignorados pelo Git
└── README.md            # Documentação do projeto

📚 依赖关系

主要依赖关系

• @模型上下文协议/sdk （^1.21.0）：Node.js 的官方 Model Context Protocol SDK
• 谷歌蜜蜂 （^164.1.0）：Node.js 的 Google API 官方客户端
• 黄道带 （^3.25.76）： TypeScript-first 架构验证库
• Dotenv。 （^17.2.3）：载入文件环境变量 .env

发展依赖关系

• @类型/节点 （^24.10.0）： Node.js 的 TypeScript 类型定义

📜 可用脚本

• npm start使用： 运行服务器 tsx
• npm run dev以观察模式运行服务器（更改后自动重新启动）

🔌 API和工具

工具 ： getMyCalendarDataByDate

查找特定日期的日历事件。

参数

• date （string， 必填）： ISO 8601 格式的日期或任何由 Date.parse()

返回

返回的是具有以下结构的 JSON 对象：

成功 ：

{
  "meetings": [
    "Reunião de Equipe at 2024-01-15T10:00:00-03:00",
    "Almoço com Cliente at 2024-01-15T12:30:00-03:00"
  ]
}

无事件 ：

{
  "meetings": []
}

错误 ：

{
  "error": "Mensagem de erro aqui"
}

🔗 链接乌斯

• 模型上下文协议文档
• Google日历API文档
• 谷歌云控制台
• Zod文档