飞书/Lark OpenAPI MCP

英语 |中文

开发者文档检索MCP |官方文档

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

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

特征

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

• 双重身份验证支持：

  • 支持App Access Token认证

  • 支持用户访问令牌认证

• 灵活的通信协议：

  • 支持标准输入/输出流（stdio）模式，适合与Trae/Cursor/Claude等AI工具集成

  • 支持服务器发送事件（SSE）模式，提供基于HTTP的接口

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

Related MCP server: Feishu/Lark OpenAPI MCP

工具清单

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

准备

创建飞书/Lark 应用

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

1. 访问飞书开放平台或Lark 开放平台并登录

2. 点击“控制台”并创建一个新的应用程序

3. 获取App ID和App Secret，用于API认证

4. 根据您的使用场景为您的应用程序添加必要的权限

5. 如果需要以用户身份调用 API，请设置 OAuth 2.0 重定向 URL 并获取用户访问令牌

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

安装 Node.js

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

在 macOS 上安装 Node.js

1. 使用 Homebrew（推荐） ：

   brew install node

2. 使用官方安装程序：

   • 访问Node.js 网站

   • 下载并安装 LTS 版本

   • 安装完成后在终端验证：

     node -v
     npm -v

在 Windows 上安装 Node.js

1. 使用官方安装程序：

   • 访问Node.js 网站

   • 下载并运行 Windows 安装程序（.msi 文件）

   • 按照安装向导完成安装

   • 安装完成后，在命令提示符中验证：

     node -v
     npm -v

2. 使用 nvm-windows ：

   • 下载nvm-windows

   • 安装 nvm-windows

   • 使用 nvm 安装 Node.js：

     nvm install latest
     nvm use <version_number>

安装

全局安装 lark-mcp 工具：

npm install -g @larksuiteoapi/lark-mcp

使用指南

与 Trae/Cursor/Claude 一起使用

要将飞书/Lark 功能集成到 Trae，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>"
      ]
    }
  }
}

自定义 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,preset.calendar.default

预设工具集合详情

下表详细介绍了每个 API 工具及其在不同预设集合中的包含情况，帮助您根据需求选择合适的预设：

注意：表中的“✓”表示该工具包含在该预设中。使用-t preset.xxx将仅启用相应列中标有“✓”的工具。

高级配置

命令行参数

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

参数使用示例

1. 基本用法（使用应用程序身份）：

   lark-mcp mcp -a cli_xxxx -s yyyyy

2. 使用用户身份：

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

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

3. 设置特定的令牌模式：

   lark-mcp mcp -a cli_xxxx -s yyyyy --token-mode user_access_token

   注意：此选项允许您明确指定调用 API 时要使用的令牌类型。 auto模式（默认）将由 LLM 在调用 API 时确定。

4. 指定 Lark 或 KA 域名：

   # 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

5. 仅启用特定 API 工具或其他 API 工具：

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

   注意： -t参数支持以下预设工具集合：

   • preset.default - 包含所有预设工具的默认工具集

   • preset.im.default - 即时通讯相关工具，例如群组管理、消息发送等。

   • preset.bitable.default - Bitable 相关工具，例如表创建、记录管理等。

   • preset.bitable.batch - Bitable批量操作工具，包含批量创建、更新记录功能

   • preset.doc.default - 文档相关工具，如文档内容读取、权限管理等。

   • preset.task.default - 任务管理相关工具，例如任务创建、成员管理等。

   • preset.calendar.default - 日历事件管理工具，例如创建日历事件、查询空闲/忙碌状态等。

6. 使用具有特定端口和主机的 SSE 模式：

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

7. 将工具语言设置为中文：

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

   注意：将语言设置为中文 ( -l zh ) 可能会消耗更多 token。如果在集成大型语言模型时遇到 token 限制问题，请考虑使用默认的英语设置 ( -l en )。

8. 将工具名称格式设置为驼峰式命名法：

   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

9. 使用环境变量代替命令行参数：

   # 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

10. 使用配置文件：

除了命令行参数外，还可以使用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": "",
  "tokenMode": "auto",
  "mode": "stdio",
  "host": "localhost",
  "port": "3000"
}

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

11. 运输方式：

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

1. stdio 模式（默认/推荐） ：适合与 Trae/Cursor 或 Claude 等 AI 工具集成，通过标准输入/输出流进行通信。

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

2. SSE模式：提供基于Server-Sent Events的HTTP接口，适用于无法本地执行的场景。

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

常问问题

• 问题：无法连接到飞书/Lark API解决方案：请检查网络连接，并确保您的 APP_ID 和 APP_SECRET 正确。请确认您可以访问飞书/Lark 开放平台 API；您可能需要配置代理。

• 问题：使用 user_access_token 时出错解决方案：检查 token 是否过期。user_access_token 的有效期通常为 2 小时，需要定期刷新。您可以实现 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 端点并正在处理事件流。

相关链接

• 飞书开放平台

• Lark国际开放平台

• 飞书开放平台API文档

• Lark 开放平台 API 文档

• Node.js 网站

• npm 文档

反馈

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