Feishu/Lark OpenAPI MCP

English | 中文

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

⚠️ 测试版通知: 该工具目前处于测试阶段。功能和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）模式，适合与Trae/Cursor/Claude等AI工具集成
  • 支持StreamableHTTP/SSE模式，提供基于HTTP的接口

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

工具列表

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

准备工作

创建Feishu/Lark应用

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

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

有关详细的应用创建和配置指南，请参阅飞书开放平台文档 - 创建应用。

安装Node.js

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

使用官方安装程序（推荐）:

1. 访问Node.js网站
2. 下载并安装LTS版本
3. 安装完成后，在终端中验证：

bash
node -v
npm -v

使用指南

与Trae/Cursor/Claude一起使用

要将Feishu/Lark功能集成到像Trae、Cursor或Claude这样的AI工具中，请使用以下按钮进行安装。

或者将以下内容添加到您的配置文件中：

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

如果您需要以用户身份访问API，您需要先在终端中使用登录命令进行登录。请注意，您需要首先在开发者控制台中配置应用程序的重定向URL，默认为http://localhost:3000/callback

bash

登录并获取用户访问令牌

npx -y @larksuiteoapi/lark-mcp login -a cli_xxxx -s yyyyy

或者可选地，使用特定OAuth范围登录 - 如果未指定，则默认授权所有权限

npx -y @larksuiteoapi/lark-mcp login -a cli_xxxx -s yyyyy --scope offline_access docx:document

然后将以下内容添加到您的配置文件中：

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

您也可以直接通过-u参数添加用户访问令牌（有效期为2小时）：

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或预设，您可以使用-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

⚠️ 注意：非预设API尚未经过兼容性测试，在理解和使用过程中AI可能无法达到最佳性能。

预设工具集详情

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

注意: 在表格中，“✓”表示该工具包含在预设中。使用 -t preset.xxx 将启用对应列中标记为“✓”的工具。

高级配置

命令行参数

lark-mcp login 命令参数:

lark-mcp logout 命令参数:

此命令用于清除本地存储的用户访问令牌。如果指定了 --app-id 参数，则只清除该应用程序的用户访问令牌；如果没有指定，则清除所有应用程序的用户访问令牌。

lark-mcp mcp 命令参数:

参数使用示例

1. 基本用法：

   bash

   使用默认设置启动，并在token过期时自动请求用户登录（推荐用于本地场景）

   lark-mcp mcp -a cli_xxxx -s yyyyy --oauth

   使用默认设置启动

   lark-mcp mcp -a cli_xxxx -s yyyyy

2. 使用用户身份：

   如果需要以用户身份访问API，首先需要使用login命令进行登录。详情请参阅“使用OAuth登录获取用户访问令牌”：

   bash

   登录并获取用户访问令牌

   lark-mcp login -a cli_xxxx -s yyyyy

   也可以手动通过-u传递user_access_token：

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

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

3. 使用OAuth登录获取用户访问令牌：
   bash

   登录并获取用户访问令牌

   lark-mcp login -a cli_xxxx -s yyyyy

   指定OAuth范围

   lark-mcp login -a cli_xxxx -s yyyyy --scope offline_access

   指定OAuth认证域

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

   注意：使用login命令将启动一个本地OAuth服务器并打开浏览器完成授权。用户访问令牌将被自动获取并安全地存储在本地，以便在后续启动中自动使用。

4. 注销并清除存储的令牌：
   bash

   清除本地存储的用户访问令牌

   lark-mcp logout

   注意：logout命令将清除本地存储的用户访问令牌。如果没有当前存储的令牌，将显示相应的消息。

5. 设置特定的令牌模式：
   bash
   lark-mcp mcp -a cli_xxxx -s yyyyy --token-mode user_access_token

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

6. 指定飞书或KA域名：
   bash

   飞书国际版

   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

7. 仅启用特定的API工具或其他API工具：
   bash
   lark-mcp mcp -a cli_xxxx -s yyyyy -t im.v1.chat.create,im.v1.message.create

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

   • preset.light - 轻量级工具集，包含较少但常用的工具，适用于需要减少令牌使用量的场景
   • preset.default - 默认工具集，包含所有预设工具
   • preset.im.default - 即时通讯相关工具，如群组管理、消息发送等> - preset.base.default - 基础相关工具，如表格创建、记录管理等。
   • preset.base.batch - 基础批量操作工具，包括批量创建和更新记录功能
   • preset.doc.default - 文档相关工具，如文档内容读取、权限管理等。
   • preset.task.default - 任务管理相关工具，如任务创建、成员管理等。
   • preset.calendar.default - 日历事件管理工具，如创建日历事件、查询空闲/忙碌状态等。

8. 设置工具语言为中文:
   bash
   lark-mcp mcp -a cli_xxxx -s yyyyy -l zh

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

9. 设置工具名称格式为驼峰式:
   bash
   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

10. 使用环境变量代替命令行参数:
    bash

设置环境变量

export APP_ID=cli_xxxx
export APP_SECRET=yyyyy
export USER_ACCESS_TOKEN=zzzzz
export LARK_TOOLS=a.b.c,a.c.d
export LARK_DOMAIN=https://open.feishu.cn
export LARK_TOKEN_MODE=user_access_token

启动服务（无需指定-a和-s参数）

lark-mcp mcp

1. 使用配置文件:

   除了命令行参数外，您还可以使用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",
   "oauth": true,
   "scope": "offline_access docx:document"
   }

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

2. 传输模式:

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

   1. 标准输入输出模式（默认/推荐）: 适用于与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 访问。

   1. Streamable模式: 提供基于StreamableHTTP的接口

   bash

   启动Streamable模式

   lark-mcp mcp -a <your_app_id> -s <your_app_secret> -m streamable --host 0.0.0.0 -p 3000

常见问题

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

• 问题: 使用user_access_token时出错
  解决方案: 检查令牌是否已过期。user_access_token通常有效期为2小时，需要定期刷新。您可以实现自动刷新令牌的机制。

• 问题: 启动MCP服务后无法调用某些API，出现权限不足错误
  解决方案: 检查您的应用程序是否已获得相应的API权限。某些API需要额外的高级权限，这些可以在开发者控制台中配置。确保权限已被批准。

• 问题: 图片或文件上传/下载相关的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端点并处理事件流。

相关链接

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

反馈

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