飞书/Lark OpenAPI MCP

English |中文

⚠️ Beta 版本公告：此工具目前处于 Beta 阶段。功能和 API 可能会有所变更，请持续关注版本更新。

这是飞书/Lark 官方 OpenAPI MCP（模型上下文协议）工具，旨在帮助用户快速接入飞书/Lark 平台，实现 AI 助手与飞书/Lark 的高效协同。该工具将飞书/Lark 开放平台 API 接口封装为 MCP 工具，AI 助手可以直接调用这些接口，实现文档处理、对话管理、日历安排等各种自动化场景。

特征

**完整的飞书/Lark API 工具包：**封装了几乎所有飞书/Lark API 接口，包括消息管理、群组管理、文档操作、日历事件、Bitable 等核心功能区。
双重身份验证支持：
- 支持App Access Token认证
- 支持用户访问令牌认证
灵活的通信协议：
- 支持标准输入/输出流（stdio）模式，适合与Cursor/Claude等AI工具集成
- 支持服务器发送事件（SSE）模式，提供基于HTTP的接口
支持多种配置方式，适应不同使用场景

工具清单

所有受支持的飞书/Lark 工具的完整列表可以在tools.md中找到，其中工具按项目和版本分类并附带说明。

准备

创建飞书/Lark 应用

使用 lark-mcp 工具前，你需要创建一个飞书/Lark 应用：

访问飞书开放平台或Lark 开放平台并登录
点击“开始”并创建一个新的应用程序
获取App ID和App Secret，用于API认证
根据您的使用场景为您的应用程序添加必要的权限
如果需要以用户身份调用 API，请设置 OAuth 2.0 重定向 URL 并获取用户访问令牌

详细的应用创建及配置指南，请参考飞书开放平台文档-创建应用或Lark 开放平台文档。

安装 Node.js

使用 lark-mcp 工具之前，需要安装 Node.js 环境。

在 macOS 上安装 Node.js

使用 Homebrew（推荐） ：
brew install node
使用官方安装程序：
- 访问Node.js 网站
- 下载并安装 LTS 版本
- 安装完成后在终端验证：
  node -v npm -v

在 Windows 上安装 Node.js

使用官方安装程序：
- 访问Node.js 网站
- 下载并运行 Windows 安装程序（.msi 文件）
- 按照安装向导完成安装
- 安装完成后，在命令提示符中验证：
  node -v npm -v
使用 nvm-windows ：
- 下载nvm-windows
- 安装 nvm-windows
- 使用 nvm 安装 Node.js：
  nvm install latest nvm use <version_number>

安装

全局安装 lark-mcp 工具：

npm install -g @larksuiteoapi/lark-mcp

使用指南

与 Cursor/Claude 一起使用

要将飞书/Lark 功能集成到 Cursor 或 Claude 等 AI 工具中，请在配置文件中添加以下内容：

{
  "mcpServers": {
    "lark-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@larksuiteoapi/lark-mcp",
        "mcp",
        "-a",
        "<your_app_id>",
        "-s",
        "<your_app_secret>"
      ]
    }
  }
}

要使用用户身份访问 API，您可以添加用户访问令牌：

{
  "mcpServers": {
    "lark-mcp": {
     "command": "npx",
      "args": [
        "-y",
        "@larksuiteoapi/lark-mcp",
        "mcp",
        "-a",
        "<your_app_id>",
        "-s",
        "<your_app_secret>",
        "-u",
        "<your_user_token>"
      ]
    }
  }
}

高级配置

命令行参数

lark-mcp工具提供了丰富的命令行参数，可以灵活地配置 MCP 服务：

范围	短的	描述	例子
`--app-id`	`-a`	飞书/Lark 应用 App ID	`-a cli_xxxx`
`--app-secret`	`-s`	飞书/Lark 应用 App Secret	`-s xxxx`
`--domain`	`-d`	飞书/Lark API 域名，默认为飞书中国版	`-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`
`--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`

参数使用示例

基本用法（使用应用程序身份）：
lark-mcp mcp -a cli_xxxx -s yyyyy
使用用户身份：
lark-mcp mcp -a cli_xxxx -s yyyyy -u u-zzzz
指定 Lark 国际域名：
lark-mcp mcp -a cli_xxxx -s yyyyy -d https://open.larksuite.com
仅启用特定的 API 工具：
lark-mcp mcp -a cli_xxxx -s yyyyy -t im.v1.chat.create,im.v1.message.create
使用具有特定端口和主机的 SSE 模式：
lark-mcp mcp -a cli_xxxx -s yyyyy -m sse --host 0.0.0.0 -p 3000
将工具语言设置为中文：
lark-mcp mcp -a cli_xxxx -s yyyyy -l zh
注意：将语言设置为中文 ( -l zh ) 可能会消耗更多 token。如果在集成大型语言模型时遇到 token 限制问题，请考虑使用默认的英语设置 ( -l en )。
将工具名称格式设置为驼峰式命名法：
lark-mcp mcp -a cli_xxxx -s yyyyy -c camel
注意：通过设置工具名称格式，您可以更改工具名称在 MCP 中的显示方式。例如， im.v1.message.create有以下不同格式：
- 蛇形格式（默认）： im_v1_message_create
- 骆驼格式： imV1MessageCreate
- kebab格式： im-v1-message-create
- 点格式： im.v1.message.create
使用环境变量代替命令行参数：
# Set environment variables export APP_ID=cli_xxxx export APP_SECRET=yyyyy # Start the service (no need to specify -a and -s parameters) lark-mcp mcp

使用配置文件

除了命令行参数外，还可以使用JSON格式的配置文件来设置参数：

lark-mcp mcp --config ./config.json

配置文件示例（config.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": "",
  "mode": "stdio",
  "host": "localhost",
  "port": "3000"
}

注意：命令行参数的优先级高于配置文件。当同时使用命令行参数和配置文件时，命令行参数将覆盖配置文件中的相应设置。

使用用户访问令牌

如果需要以特定用户身份调用 API，则可以通过指定用户访问令牌来实现：

lark-mcp mcp -a <your_app_id> -s <your_app_secret> -u <your_user_token>

用户访问令牌可以通过飞书开放平台授权流程、 Lark开放平台授权流程获取，也可以通过API调试控制台获取。使用用户访问令牌后，将以该用户的身份进行API调用。

指定自定义域

如果你使用的是 Lark 国际版或者自定义域名，可以使用-d参数指定：

# Lark international version
lark-mcp mcp -a <your_app_id> -s <your_app_secret> -d https://open.larksuite.com

# Custom domain (KA domain)
lark-mcp mcp -a <your_app_id> -s <your_app_secret> -d https://open.your-ka-domain.com

交通方式

lark-mcp 支持两种传输模式：

stdio 模式（默认/推荐） ：适合与 Cursor 或 Claude 等 AI 工具集成，通过标准输入/输出流进行通信。
lark-mcp mcp -a <your_app_id> -s <your_app_secret> -m stdio
SSE模式：提供基于Server-Sent Events的HTTP接口，适用于Web应用或者需要网络接口的场景。
# Default listens only on localhost lark-mcp mcp -a <your_app_id> -s <your_app_secret> -m sse -p 3000 # Listen on all network interfaces (allowing remote access) 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访问。

启用更多 API

MCP 服务默认启用常用 API。如需启用其他工具或特定 API，您可以使用-t参数指定（以逗号分隔）：

lark-mcp mcp -a <your_app_id> -s <your_app_secret> -t im.v1.message.create,im.v1.message.list,im.v1.chat.create

默认支持的API列表

MCP 服务默认启用以下 API：

工具名称	功能描述
im.v1.聊天.创建	创建群聊
im.v1.聊天列表	获取群聊列表
im.v1.聊天成员.获取	获取群组成员
im.v1.消息.创建	发送消息
im.v1.消息列表	获取消息列表
wiki.v2.space.getNode	获取 Wiki 节点
wiki.v1.node.search	搜索 Wiki 节点
docx.v1.document.rawContent	获取文档内容
驱动器.v1.权限成员.创建	添加协作者权限
docx.builtin.import	导入文件
docx.builtin.search	搜索文档
bitable.v1.app.创建	创建 Bitable
bitable.v1.appTable.创建	创建 Bitable 数据表
bitable.v1.appTable.list	获取Bitable数据表列表
bitable.v1.appTableField.list	获取Bitable数据表字段列表
bitable.v1.appTableRecord.search	搜索Bitable数据表记录
bitable.v1.appTableRecord.创建	创建 Bitable 数据表记录
bitable.v1.appTableRecord.update	更新Bitable数据表记录
contact.v3.用户.batchGetId	批量获取用户ID

常问问题

问题：无法连接到飞书/Lark API解决方案：请检查网络连接，并确保您的 APP_ID 和 APP_SECRET 正确。请确认您可以访问飞书/Lark 开放平台 API；您可能需要配置代理。
问题：使用 user_access_token 时出错解决方案：检查 token 是否已过期。user_access_token 的有效期通常为 2 小时，需要定期刷新。您可以实现 token 自动刷新机制，或者改用 app_access_token。
问题：启动 MCP 服务后无法调用某些 API，提示权限不足解决方案：请检查您的应用是否已获取相应的 API 权限。部分 API 需要额外的高级权限，您可以在开发者控制台或Lark 开发者控制台中配置这些权限。请确保权限已获得批准。
问题：图片或文件上传/下载相关的 API 调用失败解决方案：当前版本不支持文件和图片上传/下载功能。这些 API 将在后续版本中支持。
问题：Windows 环境下命令行显示乱码解决方案：在命令提示符中执行chcp 65001 ，将命令行编码更改为 UTF-8。如果使用 PowerShell，可能需要更改终端字体或 PowerShell 配置。
问题：安装过程中出现权限错误解决方案：macOS/Linux 用户请使用sudo npm install -g @larksuiteoapi/lark-mcp安装，或修改 npm 全局安装路径的权限。Windows 用户可尝试以管理员身份运行命令提示符。
问题：启动 MCP 服务后超出 Token 限制解决方案：尝试使用-t减少启用的 API 数量，或者使用支持更大 Token 的机型（例如 claude3.7）。
问题：无法在 SSE 模式下连接或接收消息解决方案：检查端口是否已被使用，并尝试切换到其他端口。确保客户端已正确连接到 SSE 端点并正在处理事件流。

反馈

欢迎提交问题来帮助改进此工具。如果您有任何问题或建议，请在 GitHub 仓库中提出。

Feishu/Lark OpenAPI MCP

Integrations