# 飞书/Lark OpenAPI MCP
[](https://www.npmjs.com/package/@larksuiteoapi/lark-mcp)
[](https://www.npmjs.com/package/@larksuiteoapi/lark-mcp)
[](https://nodejs.org/)
中文 | [English](./README.md)
[开发文档检索 MCP](./README_RECALL_ZH.md) | [官方文档](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/mcp_integration/mcp_introduction)
> **⚠️ Beta版本提示**：当前工具处于Beta版本阶段，功能和API可能会有变更，请密切关注版本更新。
这是飞书/Lark官方 OpenAPI MCP（Model Context Protocol）工具，旨在帮助用户快速连接飞书平台并实现 AI Agent 与飞书的高效协作。该工具将飞书开放平台的 API 接口封装为 MCP 工具，使 AI 助手能够直接调用这些接口，实现文档处理、会话管理、日历安排等多种自动化场景。
## 特点
- **完整的飞书 API 工具集：** 封装了几乎全部飞书/Lark API 接口，包括消息管理、群组管理、文档操作、日历事件、多维表格等核心功能区域。
- **双重身份验证支持：**
- 支持应用访问令牌（App Access Token）身份验证
- 支持用户访问令牌（User Access Token）身份验证
- **灵活的通信协议：**
- 支持标准输入输出流（stdio）模式，适合与 Trae/Cursor/Claude 等 AI 工具集成
- 支持服务器发送事件（SSE）模式，提供基于 HTTP 的接口
- 支持多种配置方式，适应不同的使用场景
## 工具列表
所有支持的飞书/Lark工具列表可以在[tools.md](./docs/tools-zh.md)中查看，文档按项目和版本分类列出了所有可用工具及其描述。
## 使用准备
### 创建应用
在使用lark-mcp工具前，您需要先创建一个飞书应用：
1. 访问[飞书开放平台](https://open.feishu.cn/)并登录
2. 点击"开发者后台"，创建一个新应用
3. 获取应用的App ID和App Secret，这将用于API认证
4. 根据您的使用场景，为应用添加所需的权限
5. 如需以用户身份调用API，请设置OAuth 2.0重定向URL并获取用户访问令牌
详细的应用创建和配置指南，请参考[飞书开放平台文档 - 创建应用](https://open.feishu.cn/document/home/introduction-to-custom-app-development/self-built-application-development-process#a0a7f6b0)。
### 安装Node.js
在使用lark-mcp工具之前，您需要先安装Node.js环境。
#### macOS 安装Node.js
1. **使用Homebrew安装（推荐）**：
```bash
brew install node
```
2. **使用官方安装包**：
- 访问[Node.js官网](https://nodejs.org/)
- 下载并安装LTS版本
- 安装完成后，打开终端验证：
```bash
node -v
npm -v
```
#### Windows安装Node.js
1. **使用官方安装包**：
- 访问[Node.js官网](https://nodejs.org/)
- 下载并运行Windows安装程序（.msi文件）
- 按照安装向导操作，完成安装
- 安装完成后，打开命令提示符验证：
```bash
node -v
npm -v
```
2. **使用nvm-windows**：
- 下载[nvm-windows](https://github.com/coreybutler/nvm-windows/releases)
- 安装nvm-windows
- 使用nvm安装Node.js：
```bash
nvm install latest
nvm use <版本号>
```
## 安装
全局安装lark-mcp工具：
```bash
npm install -g @larksuiteoapi/lark-mcp
```
## 使用指南
### 在Trae/Cursor/Claude中使用
如需在Trae、Cursor或Claude等AI工具中集成飞书/Lark功能，可以在配置文件中添加以下内容：
```json
{
"mcpServers": {
"lark-mcp": {
"command": "npx",
"args": [
"-y",
"@larksuiteoapi/lark-mcp",
"mcp",
"-a",
"<your_app_id>",
"-s",
"<your_app_secret>"
]
}
}
}
```
如需使用用户身份访问API，可以添加用户访问令牌：
```json
{
"mcpServers": {
"lark-mcp": {
"command": "npx",
"args": [
"-y",
"@larksuiteoapi/lark-mcp",
"mcp",
"-a",
"<your_app_id>",
"-s",
"<your_app_secret>",
"-u",
"<your_user_token>"
]
}
}
}
```
### 自定义配置开启API
默认情况下，MCP服务启用常用API，如需启用其他工具或仅启用特定API或者preset，可以通过 `-t` 参数指定（用逗号分隔）：
```bash
lark-mcp mcp -a <your_app_id> -s <your_app_secret> -t im.v1.message.create,im.v1.message.list,im.v1.chat.create,preset.calendar.default
```
#### 预设工具集（Preset）详细说明
下表详细列出了每个API工具所属的预设工具集，便于您根据实际需求选择合适的preset：
| 工具名称 | 功能描述 | preset.light | preset.default (默认) | preset.im.default | preset.base.default | preset.base.batch | preset.doc.default | preset.task.default | preset.calendar.default |
| --- | --- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
| im.v1.chat.create | 创建群 | | ✓ | ✓ | | | | | |
| im.v1.chat.list | 获取群列表 | | ✓ | ✓ | | | | | |
| im.v1.chat.search | 搜索群 | ✓ | | | | | | | |
| im.v1.chatMembers.get | 获取群成员 | | ✓ | ✓ | | | | | |
| im.v1.message.create | 发送消息 | ✓ | ✓ | ✓ | | | | | |
| im.v1.message.list | 获取消息列表 | ✓ | ✓ | ✓ | | | | | |
| bitable.v1.app.create | 创建多维表格 | | ✓ | | ✓ | ✓ | | | |
| bitable.v1.appTable.create | 创建多维表格数据表 | | ✓ | | ✓ | ✓ | | | |
| bitable.v1.appTable.list | 获取多维表格数据表列表 | | ✓ | | ✓ | ✓ | | | |
| bitable.v1.appTableField.list | 获取多维表格数据表字段列表 | | ✓ | | ✓ | ✓ | | | |
| bitable.v1.appTableRecord.search | 搜索多维表格数据表记录 | ✓ | ✓ | | ✓ | ✓ | | | |
| bitable.v1.appTableRecord.create | 创建多维表格数据表记录 | | ✓ | | ✓ | | | | |
| bitable.v1.appTableRecord.batchCreate | 批量创建多维表格数据表记录 | ✓ | | | | ✓ | | | |
| bitable.v1.appTableRecord.update | 更新多维表格数据表记录 | | ✓ | | ✓ | | | | |
| bitable.v1.appTableRecord.batchUpdate | 批量更新多维表格数据表记录 | | | | | ✓ | | | |
| docx.v1.document.rawContent | 获取文档内容 | ✓ | ✓ | | | | ✓ | | |
| docx.builtin.import | 导入文档 | ✓ | ✓ | | | | ✓ | | |
| docx.builtin.search | 搜索文档 | ✓ | ✓ | | | | ✓ | | |
| drive.v1.permissionMember.create | 添加协作者权限 | | ✓ | | | | ✓ | | |
| wiki.v2.space.getNode | 获取知识库节点 | ✓ | ✓ | | | | ✓ | | |
| wiki.v1.node.search | 搜索知识库节点 | | ✓ | | | | ✓ | | |
| contact.v3.user.batchGetId | 批量获取用户ID | ✓ | ✓ | | | | | | |
| task.v2.task.create | 创建任务 | | | | | | | ✓ | |
| task.v2.task.patch | 修改任务 | | | | | | | ✓ | |
| task.v2.task.addMembers | 添加任务成员 | | | | | | | ✓ | |
| task.v2.task.addReminders | 添加任务提醒 | | | | | | | ✓ | |
| calendar.v4.calendarEvent.create | 创建日历事件 | | | | | | | | ✓ |
| calendar.v4.calendarEvent.patch | 修改日历事件 | | | | | | | | ✓ |
| calendar.v4.calendarEvent.get | 获取日历事件 | | | | | | | | ✓ |
| calendar.v4.freebusy.list | 查询忙闲状态 | | | | | | | | ✓ |
| calendar.v4.calendar.primary | 获取主日历 | | | | | | | | ✓ |
> **说明**：表格中"✓"表示该工具包含在对应的预设工具集中。使用`-t preset.xxx`参数时，会启用该列标有"✓"的工具。
### 高级配置
#### 命令行参数说明
`lark-mcp mcp`工具提供了多种命令行参数，以便您灵活配置MCP服务：
| 参数 | 简写 | 描述 | 示例 |
|------|------|------|------|
| `--app-id` | `-a` | 飞书/Lark应用的App ID | `-a cli_xxxx` |
| `--app-secret` | `-s` | 飞书/Lark应用的App Secret | `-s xxxx` |
| `--domain` | `-d` | 飞书/Lark API域名，默认为https://open.feishu.cn | `-d https://open.larksuite.com` |
| `--tools` | `-t` | 需要启用的API工具列表，用逗号分隔 | `-t im.v1.message.create,im.v1.chat.create` |
| `--tool-name-case` | `-c` | 工具注册名称的命名格式，可选值为snake、camel、dot或kebab，默认为snake | `-c camel` |
| `--language` | `-l` | 工具语言，可选值为zh或en，默认为en | `-l zh` |
| `--user-access-token` | `-u` | 用户访问令牌，用于以用户身份调用API | `-u u-xxxx` |
| `--token-mode` | | API令牌类型，可选值为auto、tenant_access_token或user_access_token，默认为auto | `--token-mode user_access_token` |
| `--mode` | `-m` | 传输模式，可选值为stdio或sse，默认为stdio | `-m sse` |
| `--host` | | SSE模式下的监听主机，默认为localhost | `--host 0.0.0.0` |
| `--port` | `-p` | SSE模式下的监听端口，默认为3000 | `-p 3000` |
| `--config` | | 配置文件路径，支持JSON格式 | `--config ./config.json` |
| `--version` | `-V` | 显示版本号 | `-V` |
| `--help` | `-h` | 显示帮助信息 | `-h` |
#### 参数使用示例
1. **基本用法**（使用应用身份）：
```bash
lark-mcp mcp -a cli_xxxx -s yyyyy
```
2. **使用用户身份**：
```bash
lark-mcp mcp -a cli_xxxx -s yyyyy -u u-zzzz
```
> **说明**：用户访问令牌可以通过[飞书开放平台的授权流程](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/authentication-management/access-token/get-user-access-token)获取，你也可以使用API调试台获取。使用用户访问令牌后，API调用将以该用户的身份进行。
3. **设置特定的令牌模式**：
```bash
lark-mcp mcp -a cli_xxxx -s yyyyy --token-mode user_access_token
```
> **说明**：此选项允许您明确指定调用API时使用的令牌类型。`auto`模式（默认）将会由LLM在调用API的时候判断
4. **指定Lark或KA域名**：
```bash
# Lark国际版
lark-mcp mcp -a <your_app_id> -s <your_app_secret> -d https://open.larksuite.com
# 自定义域名（KA域名）
lark-mcp mcp -a <your_app_id> -s <your_app_secret> -d https://open.your-ka-domain.com
```
5. **只启用特定API工具或者其他API工具**：
```bash
lark-mcp mcp -a cli_xxxx -s yyyyy -t im.v1.chat.create,im.v1.message.create
```
> **说明**：`-t`参数支持以下预设工具集：
> - `preset.light` - 轻量级工具集，包含常用但数量较少的工具，适合减少token使用量的场景
> - `preset.default` - 默认工具集，包含所有预设工具
> - `preset.im.default` - 即时消息相关工具，如群组管理、消息发送等
> - `preset.base.default` - 多维表格相关工具，如表格创建、记录管理等
> - `preset.base.batch` - 多维表格批量操作工具，包含批量创建和更新记录功能
> - `preset.doc.default` - 文档相关工具，如文档内容读取、权限管理等
> - `preset.task.default` - 任务管理相关工具，如创建任务、添加成员等
> - `preset.calendar.default` - 日历事件管理工具，如创建日历事件、查询忙闲状态等
6. **使用SSE模式并指定端口和主机**：
```bash
lark-mcp mcp -a cli_xxxx -s yyyyy -m sse --host 0.0.0.0 -p 3000
```
7. **设置工具语言为中文**：
```bash
lark-mcp mcp -a cli_xxxx -s yyyyy -l zh
```
> **注意**：设置语言为中文(`-l zh`)可能会消耗更多的token，如果在与大模型集成时遇到token限制问题，可以考虑使用默认的英文(`-l en`)。
8. **设置工具名称格式为驼峰式**：
```bash
lark-mcp mcp -a cli_xxxx -s yyyyy -c camel
```
> **说明**：通过设置工具名称格式，可以改变工具在MCP中注册的调用名称格式。例如，`im.v1.message.create`在不同格式下的表现形式：
> - snake格式(默认): `im_v1_message_create`
> - camel格式: `imV1MessageCreate`
> - kebab格式: `im-v1-message-create`
> - dot格式: `im.v1.message.create`
9. **使用环境变量代替命令行参数**：
```bash
# 设置环境变量
export APP_ID=cli_xxxx
export APP_SECRET=yyyyy
# 启动服务（无需指定-a和-s参数）
lark-mcp mcp
```
10. **使用配置文件**：
除了命令行参数外，您还可以使用JSON格式的配置文件来设置参数：
```bash
lark-mcp mcp --config ./config.json
```
配置文件示例（config.json）：
```json
{
"appId": "cli_xxxx",
"appSecret": "xxxx",
"domain": "https://open.feishu.cn",
"tools": ["im.v1.message.create","im.v1.chat.create"],
"toolNameCase": "snake",
"language": "zh",
"userAccessToken": "",
"tokenMode": "auto",
"mode": "stdio",
"host": "localhost",
"port": "3000"
}
```
> **说明**：命令行参数优先级高于配置文件。当同时使用命令行参数和配置文件时，命令行参数会覆盖配置文件中的对应设置。
11. **传输模式**：
lark-mcp支持两种传输模式：
1. **stdio模式（默认/推荐）**：适用于与Trae/Cursor或Claude等AI工具集成，通过标准输入输出流进行通信。
```bash
lark-mcp mcp -a <your_app_id> -s <your_app_secret> -m stdio
```
2. **SSE模式**：提供基于Server-Sent Events的HTTP接口，适用于不能在本地运行的场景
```bash
# 默认只监听localhost
lark-mcp mcp -a <your_app_id> -s <your_app_secret> -m sse -p 3000
# 监听所有网络接口（允许远程访问）
lark-mcp mcp -a <your_app_id> -s <your_app_secret> -m sse --host 0.0.0.0 -p 3000
```
启动后，SSE端点将可在 `http://<host>:<port>/sse` 访问。
## 常见问题
- **问题**: 无法连接到飞书/Lark API
**解决方案**: 请检查您的网络连接，并确保APP_ID和APP_SECRET正确。检查是否能正常访问飞书开放平台API，可能需要配置代理。
- **问题**: 使用user_access_token报错
**解决方案**: 检查token是否过期，user_access_token有效期通常为2小时，需要定期刷新。您可以实现token自动刷新机制。
- **问题**: 启动MCP服务后无法调用某些API, 调用提示权限不足
**解决方案**: 检查您的应用是否已获得相应API的权限，部分API需要额外申请高级权限, 可在[开发者后台](https://open.feishu.cn/app)中进行配置。确保权限已被审批通过。
- **问题**: 图片或文件上传/下载相关API调用失败
**解决方案**: 当前版本暂不支持文件和图片的上传下载功能，此类API将在后续版本中支持。
- **问题**: Windows环境下命令行显示乱码
**解决方案**: 将命令行编码更改为UTF-8，在命令提示符中执行`chcp 65001`。如使用PowerShell，可能需要更改终端字体或PowerShell配置。
- **问题**: 安装时遇到权限错误
**解决方案**: 在macOS/Linux上使用`sudo npm install -g @larksuiteoapi/lark-mcp`进行安装，或修改npm全局安装路径的权限。Windows用户可尝试以管理员身份运行命令提示符。
- **问题**: 启动MCP服务后提示token超过上限
**解决方案**: 尝试使用 -t 减少启用的API数量，或使用支持更大token的模型（如claude3.7）
- **问题**: SSE模式下无法连接或接收消息
**解决方案**: 检查端口是否被占用，尝试更换端口。确保客户端正确连接到SSE端点并处理事件流。
## 相关链接
- [飞书开放平台](https://open.feishu.cn/)
- [开发文档：OpenAPI MCP](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/mcp_integration/mcp_introduction)
- [Lark国际版开放平台](https://open.larksuite.com/)
- [飞书开放平台API文档](https://open.feishu.cn/document/home/index)
- [Node.js官网](https://nodejs.org/)
- [npm文档](https://docs.npmjs.com/)
## 反馈
欢迎提交Issues来帮助改进这个工具。如有问题或建议，请在GitHub仓库中提出。
