飞书日历 MCP 服务器

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

功能特性

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

快速开始

1. 安装依赖

npm install
npm run build

2. 获取飞书应用凭证

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

3. 配置应用权限

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

进入你的应用管理页面
权限管理 → 权限配置，开通以下权限：
- 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

注意事项

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

许可证

MIT