Feishu/Lark OpenAPI MCP

English | 中文

⚠️ Beta 版本提示: 该工具目前处于 Beta 阶段。功能和 API 可能会发生变动，因此请关注版本更新。

这是我们为飞书/Lark 官方 OpenAPI MCP (Model Context Protocol) 打造的工具，旨在帮助用户快速连接到飞书/Lark 平台，并启用 AI 智能助手与飞书/Lark 的高效协作。此工具封装了飞书/Lark 开放平台的 API 接口为 MCP 工具，使 AI 助手能够直接调用这些接口并实现各种自动化场景，如文档处理、会话管理、日历排期等。

特性

• 完整的飞书/Lark API 工具包: 封装了几乎所有的飞书/Lark API 接口，包括消息管理、群组管理、文档操作、日历事件、Bitable 等核心功能领域。

• 双重认证支持:

  • 支持 App Access Token 认证
  • 支持 User Access Token 认证

• 灵活的通信协议:

  • 支持标准的输入/输出流 (stdio) 模式，适合集成类似 Cursor/Claude 的 AI 工具
  • 支持基于 Server-Sent Events 的 SSE 模式，提供 HTTP 接口

• 支持多种配置方式，适应不同的使用场景

工具列表

所有支持的飞书/Lark 工具列表见 tools.md，其中工具按项目和版本分类，并附有说明。

准备工作

创建飞书/Lark 应用

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

1. 访问 飞书开放平台 或 Lark 开放平台 并登录
2. 单击“开始”并创建一个新的应用
3. 获得 App ID 和 App Secret ，这将用于 API 认证
4. 根据您的使用场景添加必要的权限
5. 如果需要以用户身份调用 API，则设置 OAuth 2.0 重定向地址并获取用户访问令牌

如需更详细的应用创建和配置指南，请查阅 飞书开放平台文档 - 创建应用 或 Lark 开放平台文档.

安装 Node.js

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

在 macOS 上安装 Node.js

1. 使用 Homebrew（推荐）:

   bash 复制代码

   brew install node

2. 使用官方安装包:

   • 访问 Node.js 官网
   • 下载并安装长维护版本 (LTS)
   • 安装完成后，在终端中验证安装：
     bash 复制代码

     node -v
     npm -v

在 Windows 上安装 Node.js

1. 使用官方安装包:

   • 访问 Node.js 官网
   • 下载并运行 Windows 安装包 (.msi 文件)
   • 按照安装向导完成安装
   • 安装完成后，在命令提示符下验证安装：
     bash 复制代码

     node -v
     npm -v

2. 使用 nvm-windows:

   • 下载 nvm-windows
   • 安装 nvm-windows
   • 使用 nvm 安装 Node.js：
     bash 复制代码

     nvm install latest
     nvm use <version_number>

安装

全局安装 lark-mcp 工具：

npm install -g @larksuiteoapi/lark-mcp

使用指南

与 Cursor/Claude 集成

为了让 AI 工具如 Cursor 或 Claude 实现飞书/Lark 功能集成，请将以下内容添加至配置文件：

{
  "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 服务配置：

参数使用示例

1. 基础用法 (应用程序身份):

   bash 复制代码

   lark-mcp mcp -a cli_xxxx -s yyyyy

2. 使用用户身份:

   bash 复制代码

   lark-mcp mcp -a cli_xxxx -s yyyyy -u u-zzzz

3. 指定 Lark 国际域名:

   bash 复制代码

   lark-mcp mcp -a cli_xxxx -s yyyyy -d https://open.larksuite.com

4. 仅启用特定 API 工具:

   bash 复制代码

   lark-mcp mcp -a cli_xxxx -s yyyyy -t im.v1.chat.create,im.v1.message.create

5. 使用 SSE 模式并指定端口号和主机名

   bash 复制代码

   lark-mcp mcp -a cli_xxxx -s yyyyy -m sse --host 0.0.0.0 -p 3000

6. 设置工具语言为中文:

   bash 复制代码

   lark-mcp mcp -a cli_xxxx -s yyyyy -l zh

   注意: 设置语言为中文 (-l zh) 可能会消耗更多令牌。当与其他大模型集成遇到令牌超限问题时，建议使用默认英语设置 (-l en)。

7. 设置工具名字格式为 Camel 风格:

   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

8. 采用环境变量替代命令行参数:

   bash 复制代码

   # 设置环境变量
   export APP_ID=cli_xxxx
   export APP_SECRET=yyyyy
   
   # 启动服务（无需指定 -a 和 -s 参数）
   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，可以通过指定 User Access Token 来实现：

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

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

指定自定义域名

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

# 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

传输模式

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

1. stdio 模式（默认/推荐）: 适合用于和像 Cursor/Claude 等 AI 工具的集成，数据交换通过标准输入/输出流完成。

   bash 复制代码

   lark-mcp mcp -a <your_app_id> -s <your_app_secret> -m stdio

2. SSE 模式: 提供基于 Server-Sent Events 的 HTTP 接口，更适合 web 应用或是需要用网络接口的场景。

   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 访问。

启用更多 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 清单

默认 MPC 服务启用了以下 API 列表：

常见问题

• 问题: 无法连接到飞书/Lark API
  解决方法: 检查网络连通状况并且确保你的 APP_ID 和 APP_SECRET 是正确的。 验证是否能访问飞书/Lark 开放平台 API；如有需要设置代理服务器。

• 问题: 使用 user_access_token 报错
  解决方法: 检查令牌是否已经过期。 user_access_token 的有效期通常在 2 小时左右，所以可能需要定期刷新。 还可以考虑实施自动令牌续签机制或者切换到直接使用 app_access_token.

• 问题: 启动 MCP 服务后无法调用某些 API 并提示权限不足
  解决方法: 检查您的应用程序是否已获得了相应的 API 权限。有些 API 需要更多高级权限，可于 开发者控制台或Lark 开发者控制台里配置。 确保密钥权限已经被正确申请批准。

• 问题: 图片或文件上传/下载相关 API 调用失败
  解决方法: 当前版本不支持文件或图片的上传或下载功能。 相关功能将在未来的版本中引入和支持。

• 问题: 在 Windows 命令行环境下出现乱码的情况
  解决方法: 将命令行编码改设为 UTF-8。执行 chcp 65001 命令可以在 cmd 窗口中实现此更改。 如果是 PowerShell，您或许还需要调整终端字体或者 Powershell 设置。

• 问题: 安装时出现权限错误问题
  解决方法: 对于 macOS/Linux 用户，可以用 sudo npm install -g @larksuiteoapi/lark-mcp 命令重新尝试安装，或者对 npm 全局安装路径上的权限作适当修改。 Windows 用户可以尝试以管理员身份打开命令提示符来执行安装命令。

• 问题: 启动 MCU 没几秒就出现了令牌（tokens）限额超的问题
  解决方法: 尝试用 -t 减少加载的 API 数量，或者转而使用更大的 tokens 模型（例如 claude3.7）。

• 问题: 在 SSE 模式时无法正常连接或者没收到消息
  解决方法: 检查对应的端口是否已被占用，并且试着更换到另外一个未使用的端口上去监听连接请求。 此外，请确定客户端正在正确与 SSE 端点连线，并妥善接收和解析流中的数据片段。

相关链接

• 飞书开放平台
• Lark 国际开放平台
• 飞书开放平台 API 文档
• Lark 开放平台 API 文档
• Node.js 网站
• npm 文档

用户反馈

欢迎上报问题来促进此工具不断完善。若您有任何疑问或改进意见，请在 GitHub 仓库提交问题。