简介

一个工具包， enables 人工智能助手直接调用飞书/Lark API接口，用于文档处理、会话管理和日历安排等自动化场景。

简介

一个工具包， enables 人工智能助手直接调用飞书/Lark API接口，用于文档处理、会话管理和日历安排等自动化场景。

Feishu/Lark OpenAPI MCP

English | 中文

⚠️ Beta 版本通知: 该工具目前处于 Beta 阶段。功能和 API 可能会发生变化，请随时关注版本更新。

这是 Feishu/Lark 官方的 OpenAPI MCP (Model Context Protocol) 工具，旨在帮助用户快速连接到 Feishu/Lark 平台，并实现 AI 代理与 Feishu/Lark 之间的高效协作。该工具将 Feishu/Lark 开放平台的 API 接口封装为 MCP 工具，使 AI 助手可以直接调用这些接口，实现文档处理、对话管理、日程安排等多种自动化场景。

功能

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

• 双认证支持：

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

• 灵活的通信协议：

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

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

工具列表

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

准备工作

创建 Feishu/Lark 应用

在使用 lark-mcp 工具之前，您需要创建一个 Feishu/Lark 应用：

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

有关详细的应用创建和配置指南，请参阅 Feishu 开放平台文档 - 创建应用 或 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

使用指南

与 Cursor/Claude 集成

要将飞书/乐务的功能集成到像 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 服务：

参数使用示例

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

   lark-mcp mcp -a cli_xxxx -s yyyyy
   

2. 使用用户身份:

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

3. 指定飞书国际域名:

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

4. 仅启用特定的API工具:

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

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

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

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

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

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

7. 将工具名称格式设置为驼峰式:

   lark-mcp mcp -a cli_xxxx -s yyyyy -c camel
   

   注意: 通过设置工具名称格式，可以更改MCP中工具名称的显示方式。例如，im.v1.message.create 在不同格式下的表示：

   • 蛇形格式（默认）: im_v1_message_create
   • 驼峰格式: imV1MessageCreate
   • 减号格式: im-v1-message-create
   • 点格式: im.v1.message.create

8. 使用环境变量而不是命令行参数:

   # 设置环境变量
   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，可以通过指定用户访问令牌来实现：

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支持两种传输模式：

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

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

2. SSE 模式：提供基于 Server-Sent Events 的 HTTP 接口，适用于 Web 应用程序或需要网络接口的场景。

   # 默认仅监听 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 列表

默认情况下，MCP 服务启用了以下 API：

常见问题解答

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

• 问题: 使用user_access_token时出现错误 解决方案: 检查令牌是否已过期。user_access_token通常的有效期为2小时，需要定期刷新。您可以实现自动刷新令牌的机制，或者改用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服务后超出令牌限制 解决方案: 尝试使用-t减少启用的API数量，或者使用支持更大令牌的模型（例如claude3.7）。

• 问题: 在SSE模式下无法连接或接收消息 解决方案: 检查端口是否已被占用，并尝试更换其他端口。确保客户端正确连接到了SSE端点并且能够处理事件流。

相关链接

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

反馈

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

工具列表

• bitable_v1_app_create: [Feishu/Lark]-Docs-Base-App-Create a Base App-Create a base app in user-defined folder

• bitable_v1_appTable_create: [Feishu/Lark]-Docs-Base-Table-Create table-Access this API, you can add an empty data table containing only index columns, or specify some initial fields

• bitable_v1_appTableField_list: [Feishu/Lark]-Docs-Base-Field-List fields-Get all fields according to app_token and table_id

• bitable_v1_appTable_list: [Feishu/Lark]-Docs-Base-Table-List all tables-According to app_token, get all tables under app

• bitable_v1_appTableRecord_create: [Feishu/Lark]-Docs-Base-record-Create a record-Create a record

• bitable_v1_appTableRecord_search: [Feishu/Lark]-Docs-Base-record-Search records-This api is used to query existing records in the table. A maximum of 500 rows of records can be queried at a time, and paging is supported

• bitable_v1_appTableRecord_update: [Feishu/Lark]-Docs-Base-record-Update a record-Update a record

• contact_v3_user_batchGetId: [Feishu/Lark]-Contacts-User-Obtain user ID via email or mobile number-Call this interface to obtain the ID (including user_id, open_id, union_id) and status information of one or more users through their mobile phone number or email address

• docx_v1_document_rawContent: [Feishu/Lark]-Docs-Document-Document-Obtain the plain text content of the document-Obtains the plain text content of the document

• drive_v1_permissionMember_create: [Feishu/Lark]-Docs-Permission-Member-Add permissions-This API is used to add permissions on a document for a user based on a filetoken

• im_v1_chat_create: [Feishu/Lark]-Group Chat-Group management-Create a group-Create a group chat. When creating a group chat, you can set the group avatar, group name, group owner, group type and other configurations. You can also invite group members and group bots to join the group

• im_v1_chat_list: [Feishu/Lark]-Group Chat-Group management-Obtain groups where the user or bot is a member-Get the list of groups where the user or bot represented by is a member

• im_v1_chatMembers_get: [Feishu/Lark]-Group Chat-Group member-Obtain group member list-Get the list of members of the group the user/bot is in

• im_v1_message_create: [Feishu/Lark]-Messaging-Message management-Send message-Call this interface to send a message to a specified user or group chat. Supported message types include text, rich text, cards, group business cards, personal business cards, pictures, videos, audio, files, and emoticons

• im_v1_message_list: [Feishu/Lark]-Messaging-Message management-Get chat history-Obtains chat history (chat records) of chats (including private chats and group chats)

• wiki_v1_node_search: [Feishu/Lark]-Docs-Wiki-Search Wiki

• wiki_v2_space_getNode: [Feishu/Lark]-Docs-Wiki-node-Get Wiki node information-Get wiki node inforamtion

• docx_builtin_search: [Feishu/Lark]-Docs-Document-Search Document-Search cloud documents, only supports user_access_token

• docx_builtin_import: [Feishu/Lark]-Docs-Document-Import Document-Import cloud document, maximum 20MB

服务配置

[{'mcpServers': {'lark-mcp': {'args': ['-y', '@larksuiteoapi/lark-mcp', 'mcp', '-a', 'YOUR_APP_ID', '-s', 'YOUR_APP_SECRET', '-u', 'YOUR_USER_TOKEN'], 'command': 'npx'}}}]

来源

• 来源：github
• 链接：https://github.com/larksuite/lark-openapi-mcp