Information
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应用：
访问飞书开放平台或Lark开放平台并登录
点击“控制台”并创建一个新的应用
获取App ID和App Secret，这将用于API认证
根据您的使用场景为应用添加必要的权限
如果您需要以用户身份调用API，请将OAuth 2.0重定向URL设置为http://localhost:3000/callback
有关详细的应用创建和配置指南，请参阅飞书开放平台文档 - 创建应用。
安装Node.js
在使用lark-mcp工具之前，您需要安装Node.js环境。
使用官方安装程序（推荐）:
访问Node.js网站
下载并安装LTS版本
安装完成后，在终端验证：
bash
node -v
使用指南
与Trae/Cursor/Claude配合使用
要将Feishu/Lark功能集成到像Trae、Cursor或Claude这样的AI工具中，请使用以下按钮进行安装。
或者在您的配置文件中添加以下内容：
json
\{
"command": "npm",
"args": ["-y", "@larksuiteoapi/lark-mcp", "mcp", "-a", "your_app_id", "-s", "your_app_secret"]
\}如果您需要以用户身份访问API，首先需要在终端中使用登录命令进行登录。请注意，您需要先在开发者控制台中配置应用程序的重定向URL，默认为 http://localhost:3000/callback
# Login and get user access token
npx -y @larksuiteoapi/lark-mcp login -a cli_xxxx -s yyyyy
# Or optionally, login with specific OAuth scope - if not specified, all permissions will be authorized by default
npx -y @larksuiteoapi/lark-mcp login -a cli_xxxx -s yyyyy --scope offline_access docx:document
然后将以下内容添加到您的配置文件中：
\{
"mcpServers": \{
"lark-mcp": \{
"command": "npx",
"args": [
"-y",
"@larksuiteoapi/lark-mcp",
"mcp",
"-a",
"",
"-s",
"",
"--oauth"
]
\}
\}
\}
您也可以直接通过-u参数添加用户访问令牌（有效期为2小时）：
\{
"mcpServers": \{
"lark-mcp": \{
"command": "npx",
"args": [
"-y",
"@larksuiteoapi/lark-mcp",
"mcp",
"-a",
"",
"-s",
"",
"-u",
""
]
\}
\}
\}
自定义API配置
默认情况下，MCP服务启用了常用API。要启用其他工具或仅特定API或预设，可以使用-t参数指定它们（用逗号分隔）：
lark-mcp mcp -a -s -t im.v1.message.create,im.v1.message.list,im.v1.chat.create,preset.calendar.default
⚠️ 注意：非预设API尚未经过兼容性测试，在理解和使用过程中AI可能无法达到最佳性能。
详细预设工具集合
下表详细列出了每个API工具及其在不同预设集合中的包含情况，帮助您根据需求选择合适的预设：
工具名称功能描述preset.lightpreset.default (默认)preset.im.defaultpreset.base.defaultpreset.base.batchpreset.doc.defaultpreset.task.defaultpreset.calendar.defaultim.v1.chat.create创建群聊✓✓im.v1.chat.list获取群聊列表✓✓im.v1.chat.search搜索群聊✓im.v1.chatMembers.get获取群成员✓✓im.v1.message.create发送消息✓✓✓im.v1.message.list获取消息列表✓✓✓bitable.v1.app.create创建基础✓✓✓bitable.v1.appTable.create创建基础数据表✓✓✓bitable.v1.appTable.list获取基础数据表列表✓✓✓bitable.v1.appTableField.list获取基础数据表字段列表✓✓✓bitable.v1.appTableRecord.search搜索基础数据表记录✓✓✓✓bitable.v1.appTableRecord.create创建基础数据表记录✓✓bitable.v1.appTableRecord.batchCreate批量创建基础数据表记录✓✓bitable.v1.appTableRecord.update更新基础数据表记录✓✓bitable.v1.appTableRecord.batchUpdate批量更新基础数据表记录✓docx.v1.document.rawContent获取文档内容✓✓✓docx.builtin.import导入文档✓✓✓docx.builtin.search搜索文档✓✓✓drive.v1.permissionMember.create添加协作者权限✓✓wiki.v2.space.getNode获取Wiki节点✓✓✓wiki.v1.node.search搜索Wiki节点✓✓contact.v3.user.batchGetId批量获取用户ID✓✓task.v2.task.create创建任务✓task.v2.task.patch修改任务✓task.v2.task.addMembers添加任务成员✓task.v2.task.addReminders添加任务提醒✓calendar.v4.calendarEvent.create创建日历事件✓calendar.v4.calendarEvent.patch修改日历事件✓calendar.v4.calendarEvent.get获取日历事件✓calendar.v4.freebusy.list查询空闲/忙碌状态✓calendar.v4.calendar.primary获取主日历✓
注意：表中"✓"表示该工具被包含在对应的预设中。使用-t preset.xxx将启用对应列中标记为"✓"的工具。
高级配置
命令行参数
lark-mcp login命令参数：| 参数 | 简写 | 描述 | 示例 |
|------|------|------|------|
| --app-id | -a | 飞书/飞鸽应用的App ID | -a cli_xxxx |
| --app-secret | -s | 飞书/飞鸽应用的App Secret | -s xxxx |
| --domain | -d | 飞书/飞鸽 API 域名，默认为 https://open.feishu.cn | -d https://open.larksuite.com |
| --host | | 监听主机，默认为 localhost | --host localhost |
| --port | -p | 监听端口，默认为 3000 | -p 3000 |
| --scope | | 指定用户访问令牌的OAuth范围，默认为授予应用的所有权限，用空格或逗号分隔 | --scope offline_access docx:document |
lark-mcp logout 命令参数：
参数简写描述示例--app-id-a飞书/飞鸽应用的App ID（可选）。如果指定，则仅清除该应用的令牌；如果不指定，则清除所有应用的令牌-a cli_xxxx
此命令用于清除本地存储的用户访问令牌。如果指定了 --app-id 参数，则只清除该应用的用户访问令牌；如果没有指定，则清除所有应用的用户访问令牌。
lark-mcp mcp 命令参数：
参数简写描述示例--app-id-a飞书/飞鸽应用的App ID-a cli_xxxx--app-secret-s飞书/飞鸽应用的App Secret-s xxxx--domain-d飞书/飞鸽 API 域名，默认为 https://open.feishu.cn-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--token-modeAPI令牌类型，选项有 auto, tenant_access_token 或 user_access_token，默认为 auto--token-mode user_access_token--oauth启用MCP认证服务器以获取用户访问令牌，并在令牌过期时自动请求用户登录（Beta）--oauth--scope指定用户访问令牌的OAuth范围，默认为授予应用的所有权限，用空格或逗号分隔--scope offline_access docx:document--mode-m传输模式，选项有 stdio, streamable 或 sse，默认为 stdio-m streamable--hostSSE/Streamable模式下的监听主机，默认为 localhost--host 0.0.0.0--port-pSSE/Streamable模式下的监听端口，默认为 3000-p 3000--config配置文件路径，支持JSON格式--config ./config.json--version-V显示版本号-V--help-h显示帮助信息-h
参数使用示例
基本用法：
# Start with default settings and auto request user login when token expires (recommended for local scenarios)
lark-mcp mcp -a cli_xxxx -s yyyyy --oauth
# Start with default settings
lark-mcp mcp -a cli_xxxx -s yyyyy
使用用户身份：
如果需要以用户身份访问API，首先需要使用login命令登录。详情请参阅“使用OAuth登录获取用户访问令牌”：
# Login and get user access token
lark-mcp login -a cli_xxxx -s yyyyy
也可以手动通过 -u 传递 user_access_token：
lark-mcp mcp -a cli_xxxx -s yyyyy -u u-zzzz
注意：用户访问令牌可以通过飞书开放平台的授权流程获得，或者可以使用API调试控制台来获取。使用了用户访问令牌后，将以该用户的名义进行API调用。
使用OAuth登录获取用户访问令牌：
# Login and get user access token
lark-mcp login -a cli_xxxx -s yyyyy
# Specify OAuth scope
lark-mcp login -a cli_xxxx -s yyyyy --scope offline_access
# Specify domain for OAuth authentication
lark-mcp login -a cli_xxxx -s yyyyy -d https://open.larksuite.com
注意：使用 login 命令将启动一个本地OAuth服务器并打开浏览器完成授权。用户访问令牌将被自动获取并安全地存储在本地，以便在后续启动时自动使用。
注销并清除存储的令牌：
PLACEHOLDER_CODE_10> 注意: logout 命令将清除本地存储的用户访问令牌。如果当前没有存储的令牌，将显示相应的消息。
设置特定令牌模式:
lark-mcp mcp -a cli_xxxx -s yyyyy --token-mode user_access_token
注意: 此选项允许您在调用 API 时显式指定要使用的令牌类型。auto 模式（默认）将在调用 API 时由 LLM 确定。
指定飞书或 KA 域名:
# Lark international version
lark-mcp mcp -a -s -d https://open.larksuite.com
# Custom domain (KA domain)
lark-mcp mcp -a -s -d https://open.your-ka-domain.com
仅启用特定的 API 工具或其他 API 工具:
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 - 日历事件管理工具，如创建日历事件、查询空闲/忙碌状态等
将工具语言设置为中文:
lark-mcp mcp -a cli_xxxx -s yyyyy -l zh
注意: 将语言设置为中文 (-l zh) 可能会消耗更多令牌。如果您在与大型语言模型集成时遇到令牌限制问题，请考虑使用默认的英文设置 (-l en)。
将工具名称格式设置为驼峰命名法:
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
使用环境变量代替命令行参数:
# Set environment variables
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
# 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": "",
"tokenMode": "auto",
"mode": "stdio",
"host": "localhost",
"port": "3000",
"oauth": true,
"scope": "offline_access docx:document"
\}
注意: 命令行参数的优先级高于配置文件。当同时使用命令行参数和配置文件时，命令行参数将覆盖配置文件中的相应设置。
传输模式:
lark-mcp 支持三种传输模式：
标准输入输出模式（默认/推荐）: 适合与像 Trae/Cursor 或 Claude 这样的 AI 工具集成，通过标准输入输出流进行通信。
lark-mcp mcp -a -s -m stdio
SSE 模式: 提供基于 Server-Sent Events 的 HTTP 接口，适用于无法在本地执行的场景。
# Default listens only on localhost
lark-mcp mcp -a -s -m sse -p 3000
# Listen on all network interfaces (allowing remote access)
lark-mcp mcp -a -s -m sse --host 0.0.0.0 -p 3000
启动后，SSE 端点将可以通过 http://:/sse 访问。
可流式处理模式: 提供基于 StreamableHTTP 的接口
# Start streamable mode
lark-mcp mcp -a -s -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仓库中提出。