飞书日历 MCP 服务器

Feishu Calendar MCP Server - 用于将飞书日历 API 包装成 Model Context Protocol (MCP) 服务器。

功能特性

• 日历管理: 获取、创建、更新、删除日历
• 日程管理: 获取、创建、更新、删除日程事件
• 订阅管理: 订阅/取消订阅日历
• 忙碌状态: 查询用户忙碌状态和可用时间
• 简单认证: 支持多种认证方式，推荐使用 app_access_token（最简单）

快速开始

1. 安装依赖

npm install
npm run build

2. 获取飞书应用凭证

1. 访问 飞书开放平台
2. 创建自建应用
3. 获取 App ID 和 App Secret

3. 配置应用权限

在飞书开放平台配置应用：

1. 进入你的应用管理页面
2. 权限管理 → 权限配置，开通以下权限：
   • calendar:calendar - 查看、管理日历
   • calendar:event - 查看、创建、编辑日程

4. 配置认证方式

本服务器支持三种认证方式，推荐使用方式一（最简单）：

---

方式一：App Access Token（推荐，最简单）

只需配置 app_id 和 app_secret，系统自动获取 app_access_token。

FEISHU_APP_ID=cli_xxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxx
FEISHU_USE_APP_TOKEN=true

无需任何额外配置，这是最简单的方式！

---

方式二：Refresh Token（自动刷新）

通过 OAuth 授权获取 refresh_token，系统会自动刷新 access_token。

FEISHU_APP_ID=cli_xxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxx
FEISHU_REFRESH_TOKEN=你的刷新令牌

运行授权脚本获取 refresh_token：

npm run auth

按照提示在浏览器中完成授权，refresh_token 会自动保存到 .env 文件。

---

方式三：User Access Token（手动管理）

直接使用 user_access_token，但需要注意 token 有效期约 2 小时，过期需要重新获取。

FEISHU_APP_ID=cli_xxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxx
FEISHU_USER_ACCESS_TOKEN=你的用户访问令牌

5. 在 Claude Desktop 中使用

编辑 Claude Desktop 配置文件：

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

配置方式选择

根据你的安装方式选择对应的配置：

---

方式一：全局安装（推荐，最简单）

先全局安装：

npm install -g feishu-calendar-mcp

配置：

{
  "mcpServers": {
    "feishu-calendar": {
      "command": "feishu-calendar-mcp",
      "args": [],
      "env": {
        "FEISHU_APP_ID": "your_app_id",
        "FEISHU_APP_SECRET": "your_app_secret",
        "FEISHU_USE_APP_TOKEN": "true"
      }
    }
  }
}

---

方式二：使用 npx（无需安装）

配置：

{
  "mcpServers": {
    "feishu-calendar": {
      "command": "npx",
      "args": ["-y", "feishu-calendar-mcp"],
      "env": {
        "FEISHU_APP_ID": "your_app_id",
        "FEISHU_APP_SECRET": "your_app_secret",
        "FEISHU_USE_APP_TOKEN": "true"
      }
    }
  }
}

---

方式三：本地开发路径

如果你在开发目录下使用：

{
  "mcpServers": {
    "feishu-calendar": {
      "command": "node",
      "args": ["/absolute/path/to/feishu-calendar/dist/index.js"],
      "env": {
        "FEISHU_APP_ID": "your_app_id",
        "FEISHU_APP_SECRET": "your_app_secret",
        "FEISHU_USE_APP_TOKEN": "true"
      }
    }
  }
}

---

认证方式选择

使用 App Access Token（推荐）:

"env": {
  "FEISHU_APP_ID": "your_app_id",
  "FEISHU_APP_SECRET": "your_app_secret",
  "FEISHU_USE_APP_TOKEN": "true"
}

使用 Refresh Token:

"env": {
  "FEISHU_APP_ID": "your_app_id",
  "FEISHU_APP_SECRET": "your_app_secret",
  "FEISHU_REFRESH_TOKEN": "your_refresh_token"
}

配置完成后，重启 Claude Desktop 即可使用。

6. 测试连接

npm run build
npx tsx test-client.ts

可用工具

日历相关

工具名	描述	必需参数
feishu_get_calendar_list	获取日历列表	-
feishu_get_calendar	获取日历详情	calendar_id
feishu_create_calendar	创建日历	summary
feishu_update_calendar	更新日历	calendar_id
feishu_delete_calendar	删除日历	calendar_id

日程事件相关

工具名	描述	必需参数
feishu_get_event_list	获取日程列表	calendar_id
feishu_get_event	获取日程详情	calendar_id, event_id
feishu_create_event	创建日程	calendar_id, summary, start_time, end_time
feishu_update_event	更新日程	calendar_id, event_id
feishu_delete_event	删除日程	calendar_id, event_id

订阅相关

工具名	描述	必需参数
feishu_subscribe_calendar	订阅日历	calendar_id
feishu_unsubscribe_calendar	取消订阅日历	calendar_id

忙碌状态相关

工具名	描述	必需参数
feishu_get_free_busy	查询忙碌状态	calendar_ids, start_time, end_time
feishu_get_available_time	获取可用时间	calendar_id, start_time, end_time, duration_minutes

使用示例

在 Claude Desktop 中使用

查询我的日历列表：

请帮我查询所有日历

创建一个日程：

帮我创建一个明天下午2点的会议，主题是"产品讨论会"，时长1小时

查询某段时间的空闲时间：

查询明天上午9点到12点之间，我有哪段空闲时间可以安排30分钟的会议

---

API 直接调用示例

创建日程（完整参数）

curl -i -X POST \
  'https://open.feishu.cn/open-apis/calendar/v4/calendars/{calendar_id}/events?user_id_type=open_id' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {your_user_access_token}' \
  -d '{
    "summary": "团队周会",
    "description": "每周项目进度同步会议",
    "start_time": {
      "timestamp": "1738360800",
      "timezone": "Asia/Shanghai"
    },
    "end_time": {
      "timestamp": "1738364400",
      "timezone": "Asia/Shanghai"
    },
    "visibility": "default",
    "attendee_ability": "can_see_others",
    "free_busy_status": "busy",
    "location": "会议室 A"
  }'

---

参数说明

时间参数

参数	类型	说明	示例
timestamp	string	Unix 时间戳（秒）	"1738360800"
timezone	string	时区	"Asia/Shanghai"

注意: 飞书 API 使用秒级时间戳，不是毫秒！

可见性 (visibility)

值	说明
default	默认
public	公开
private	私密

参与者能力 (attendee_ability)

值	说明
can_see_others	可见其他参与者
cannot_see_others	不可见其他参与者

忙碌状态 (free_busy_status)

值	说明
busy	忙碌
free	空闲

开发

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 构建
npm run build

注意事项

1. 认证方式: 推荐使用 app_access_token（只需 app_id 和 app_secret，最简单）
2. Token 刷新: refresh_token 会自动刷新 access_token，无需手动干预
3. 时间格式: API 使用 Unix 时间戳（秒）
4. 权限配置: 确保应用已获取足够的权限
5. API 限制: 飞书 API 有调用频率限制，请注意控制调用频率

许可证

MIT