439
下载量
16
安装量
0
收藏量
★ 5.0
综合评分ⓘ
My Lark（飞书全能力技能）#
凭证统一存放在
/workspace/.lark_tokens.json，技能本身不含任何凭证。
一、完整功能索引#
#功能场景核心工具凭证要求1发消息到群im_v1_message_createapp_id + app_secret2获取群聊列表im_v1_chat_listapp_id + app_secret3创建群聊im_v1_chat_createapp_id + app_secret4搜索云文档docx_builtin_searchuser_access_token5读取文档内容docx_v1_document_rawContentuser_access_token6读写电子表格sheets_v2_spreadsheets_values_*app_id + app_secret7搜索知识库wiki_v1_node_searchuser_access_token8查询多维表格bitable_v1_appTableRecord_*app_id + app_secret9查日历/建日程calendar_v4_eventsapp_id + app_secret10查询通讯录contact_v3_user_batchGetIdapp_id + app_secret11提交/查审批approval_v4_instances_*app_id + app_secret12云盘文件管理drive_explorer_v2_fileListapp_id + app_secret13下载画板图片board/v1/whiteboards/:id/download_as_imageapp_id + app_secret14解析 PlantUML/Mermaidboard/v1/whiteboards/:id/nodes/plantumlapp_id + app_secret
二、前置条件（逐项检查）#
依赖最低要求检查命令检查失败怎么做Python≥ 3.8（建议 ≥ 3.10）python3 --version升级 Python： apt update && apt install python3.11Node.js≥ 16node --version升级 Node.jsnpm任意版本npm --version随 Node.js 自动安装lark-mcp已安装并可用lark-mcp --help见安装步骤第三步飞书应用已创建并发布飞书开放平台控制台见安装步骤第一步凭证文件已配置cat /workspace/.lark_tokens.json见安装步骤第二步
一键检查脚本（复制运行）：
bash
python3 --version && node --version && lark-mcp --help && cat /workspace/.lark_tokens.json | python3 -m json.tool && echo "✅ 全部就绪"
三、完整安装步骤#
第一步：创建飞书应用（账号要求：飞书管理员）#
操作路径：
- 打开 飞书开放平台 → 用管理员账号登录
- 点击「创建企业自建应用」→ 填写应用名称（如"MyLark Bot"）→ 点击创建
- 进入应用 → 左侧「应用功能」→「机器人」→ 点击「开启」
- 左侧「凭证与基础信息」→ 复制 App ID 和 App Secret（备用）
- 左侧「权限管理」→ 按需申请以下权限（见下方权限速查表）
- 左侧「版本管理与发布」→ 创建版本 → 申请发布 → 管理员审批
必须申请的权限（消息/群组/日历/通讯录/审批/多维表格）：
权限名用途im:message发/查消息im:chat群管理im:chat:read读取群信息calendar日历读写calendar:calendar:read读日历contact通讯录读写approval审批读写
知识库/云文档额外权限（需 User Token）：
权限名用途wiki知识库读写docx云文档读写
💡 权限申请后需重新发布版本才能生效。
第二步：配置凭证文件#
在 /workspace/.lark_tokens.json（注意是 /workspace/ 不是 ~）创建文件：
json
{
"app_id": "cli_xxxxxxxxxxxxxxxx",
"app_secret": "your_app_secret_here",
"user_access_token": "your_user_access_token_here"
}
如何获取 user_access_token（仅知识库/云文档需要）：
方式 A（简单）：在飞书开放平台 → 应用 → 权限管理 → 开通「以应用身份获取用户授权」
方式 B（标准 OAuth）：
- 构造授权 URL：
text
https://open.feishu.cn/open-apis/authen/v1/authorize?app_id=cli_xxx&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fcallback&state=randomstring
- 浏览器打开 → 扫码授权 → 回调获取
code - 用 code 换取 token：
bash
curl -X POST 'https://open.feishu.cn/open-apis/authen/v1/oidc/access_token' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer USER_ACCESS_TOKEN' \
-d '{"grant_type": "authorization_code", "code": "获取的code"}'
第三步：安装 lark-mcp CLI#
bash
npm install -g @larksuite/lark-mcp
验证安装成功：
bash
lark-mcp --help
# 出现帮助信息即表示安装成功
第四步：验证配置（逐项测试）#
bash
# 1. 确认凭证文件存在且格式正确
cat /workspace/.lark_tokens.json | python3 -m json.tool
# 应该输出格式化的 JSON，无报错
# 2. 测试 App Token（查询群列表）
python3 /workspace/skills/lark-skill/lark_mcp.py call im_v1_chat_list '{"page_size": 5}'
# 预期：返回群聊列表 JSON
# 3. 测试发消息（需要先把机器人拉入群）
python3 /workspace/skills/lark-skill/lark_mcp.py send oc_xxxxxxxxxxxxxxxx "机器人连通测试"
# 预期：飞书群收到消息
# 4. 测试通讯录查询
python3 /workspace/skills/lark-skill/lark_mcp.py call contact_v3_user_batchGetId '{}'
# 预期：返回用户信息
全部通过 → 配置完成 ✅
四、调用方式详解#
标准格式#
bash
python3 /workspace/skills/lark-skill/lark_mcp.py <命令> [参数]
命令分类#
A. 便捷命令（简化操作，无需记工具名）
命令示例说明send <chat_id> <消息>``send oc_xxx "你好"发文本消息到群chats``chats获取群聊列表（返回 chat_id）search <关键词>``search 项目报告搜索云文档（需 User Token）doc <doc_token>``doc W7FOdr5aQo9F1读取云文档全文（需 User Token）user <open_id>``user ou_xxx查询单个用户信息call <工具名> <json>``call im_v1_chat_list '{}'调用任意底层工具
B. 底层工具调用格式
bash
python3 /workspace/skills/lark-skill/lark_mcp.py call <工具名> '<JSON参数>'
⚠️ JSON 参数必须用 单引号 包裹，外层用双引号，这是 shell 转义要求。
五、每个场景的完整调用示例#
场景 1：发文本消息到群#
bash
python3 /workspace/skills/lark-skill/lark_mcp.py send oc_xxxxxxxxxxxxxxxx "各位同事，明天上午10点开会，请准时参加。"
前置：机器人已在群里（未被禁言）
场景 2：获取群聊列表（找到 chat_id）#
bash
python3 /workspace/skills/lark-skill/lark_mcp.py call im_v1_chat_list '{"page_size": 20}'
返回示例：
json
{
"data": {
"items": [
{"chat_id": "oc_xxx", "name": "技术部群"},
{"chat_id": "oc_yyy", "name": "项目协同群"}
]
}
}
取 chat_id 填入 send 命令即可发消息。
场景 3：发送富文本消息#
bash
python3 /workspace/skills/lark-skill/lark_mcp.py call im_v1_message_create '{
"receive_id": "oc_xxxxxxxxxxxxxxxx",
"msg_type": "post",
"content": "{\"zh_cn\":{\"title\":\"会议通知\",\"content\":[[{\"tag\":\"text\",\"text\":\"时间：明天上午10点\"},{\"tag\":\"text\",\"text\":\"地点：会议室A\"}]]}}"
}'
场景 4：搜索云文档#
bash
python3 /workspace/skills/lark-skill/lark_mcp.py search 项目报告
返回文档名称、token、链接等列表。
场景 5：读取云文档内容#
bash
# 先用 search 拿到 document_id，再读取内容
python3 /workspace/skills/lark-skill/lark_mcp.py doc W7FOdr5aQo9F1OxapR8cQkPpnNg
⚠️ 需要 user_access_token 配置正确。
场景 6：读写电子表格#
bash
# 读取单元格（A1:D5）
python3 /workspace/skills/lark-skill/lark_mcp.py call sheets_v2_spreadsheets_values_get '{
"spreadsheetToken": "Shtxxxxxx",
"range": "Sheet1!A1:D5"
}'
# 写入单元格
python3 /workspace/skills/lark-skill/lark_mcp.py call sheets_v2_spreadsheets_values_put '{
"spreadsheetToken": "Shtxxxxxx",
"range": "Sheet1!A1",
"values": [["姓名", "部门", "状态"], ["张三", "技术部", "在职"]]
}'
场景 7：操作多维表格（增删改查记录）#
bash
# 列出所有多维表格
python3 /workspace/skills/lark-skill/lark_mcp.py call bitable_v1_app_list '{}'
# 列出某个多维表格的所有记录
python3 /workspace/skills/lark-skill/lark_mcp.py call bitable_v1_appTableRecord_list '{
"table_id": "tblxxxxxx",
"page_size": 100
}'
# 新增一条记录
python3 /workspace/skills/lark-skill/lark_mcp.py call bitable_v1_appTableRecord_create '{
"table_id": "tblxxxxxx",
"fields": {"姓名": "李四", "部门": "产品部"}
}'
场景 8：日历管理#
bash
# 查询日历列表
python3 /workspace/skills/lark-skill/lark_mcp.py call calendar_v4_calendars '{}'
# 创建日程
python3 /workspace/skills/lark-skill/lark_mcp.py call calendar_v4_events '{
"summary": "产品评审会",
"start_time": {"timestamp": "1743225600", "timezone": "Asia/Shanghai"},
"end_time": {"timestamp": "1743229200", "timezone": "Asia/Shanghai"},
"description": "Q2产品评审，需要各位负责人参加"
}'
# 查询某人在某时段的忙闲
python3 /workspace/skills/lark-skill/lark_mcp.py call calendar_v4_freebusy_query '{
"time_min": "2026-03-30T00:00:00+08:00",
"time_max": "2026-03-31T00:00:00+08:00",
"user_ids": ["ou_xxxxxxxxxxxxxxxx"]
}'
场景 9：通讯录查询#
bash
# 查询已知用户的信息
python3 /workspace/skills/lark-skill/lark_mcp.py call contact_v3_user_batchGetId '{
"user_id_type": "open_id",
"open_ids": ["ou_032ca29de8829b1a71272844465a4df3"]
}'
# 查询部门下所有用户
python3 /workspace/skills/lark-skill/lark_mcp.py call contact_v3_users '{
"user_id_type": "open_id",
"department_id_type": "open_department_id",
"department_ids": ["od_xxxxxxxxxxxxxxxx"]
}'
场景 10：提交审批#
bash
python3 /workspace/skills/lark-skill/lark_mcp.py call approval_v4_instances_create '{
"approval_code": "APPROVAL_CODE_xxx",
"form": [
{"id": "field1", "value": ["张三的报销申请"]},
{"id": "field2", "value": ["998.50"]}
]
}'
场景 11：知识库操作#
bash
# 搜索知识库
python3 /workspace/skills/lark-skill/lark_mcp.py call wiki_v1_node_search '{
"query": "技术文档",
"count": 10
}'
# 获取知识库节点详情（需要 space_id 和 node_token）
python3 /workspace/skills/lark-skill/lark_mcp.py call wiki_v2_space_getNode '{
"space_id": "7241909889038073859",
"node_token": "xxxxxxxxxx"
}'
⚠️ 知识库相关接口需要 user_access_token。
场景 12：云盘文件管理#
bash
# 获取云盘根目录
python3 /workspace/skills/lark-skill/lark_mcp.py call drive_explorer_v2_root_folder_meta '{}'
# 列出文件夹内容
python3 /workspace/skills/lark-skill/lark_mcp.py call drive_explorer_v2_fileList '{
"order_by": 3,
"direction": "DESC"
}'
# 创建文件夹
python3 /workspace/skills/lark-skill/lark_mcp.py call drive_v1_files_create_folder '{
"name": "新文件夹",
"folder_token": "根目录token"
}'
场景 13：下载画板为图片#
bash
# 获取画板ID（从文档块中提取 white_board_token）
python3 /workspace/skills/lark-skill/lark_mcp.py call board/v1/whiteboards/{whiteboard_id}/download_as_image '{
"format": "png",
"quality": "high"
}'
场景 14：解析 PlantUML / Mermaid 语法#
bash
# 解析 PlantUML
python3 /workspace/skills/lark-skill/lark_mcp.py call board/v1/whiteboards/{whiteboard_id}/nodes/plantuml '{
"plant_uml_code": "@startuml\nAlice -> Bob: 你好\nBob --> Alice: 你好！\n@enduml",
"syntax_type": 1
}'
# 解析 Mermaid
python3 /workspace/skills/lark-skill/lark_mcp.py call board/v1/whiteboards/{whiteboard_id}/nodes/plantuml '{
"mermaid_code": "graph TD;\n A[开始] --> B{判断}\n B -->|是| C[执行]\n B -->|否| D[退出}",
"syntax_type": 2
}'
六、异常处理（完整版）#
运行时错误速查#
错误现象第一步排查解决方案报 FileNotFoundError``ls /workspace/.lark_tokens.json创建凭证文件，见第二步报 JSONDecodeError``cat /workspace/.lark_tokens.json | python3 -m json.toolJSON 格式错误，用 json.cn 校验报 app_id 或 app_secret 错误飞书开放平台 → 凭证与基础信息重新复制 App ID / App Secret报 permission denied飞书开放平台 → 权限管理申请对应权限 → 重新发布版本报 99991403「权限不足」含义广见下方分类排查报 99991700机器人不在群里手动把机器人拉入群聊报 99991140接口频率超限等 1-2 秒再试，勿频繁轮询报 99991663Token 无效或过期App Secret 可能变更，重新获取报 lark-mcp: command not found``npm list -g @larksuite/lark-mcp重新安装： npm install -g @larksuite/lark-mcp工具调用后无输出/超时报错lark-mcp --help 确认可用重启终端或重新安装 lark-mcp知识库/云文档报权限错误user_access_token 是否配置确认凭证中有 user_access_token 字段
99991403 权限不足——分类诊断#
伴随信息真正原因解决方法"无 im:message 权限"应用未申请消息权限飞书后台 → 权限管理 → 申请 im:message → 重新发版"无 calendar 权限"日历权限未开同上，申请 calendar → 重新发版"无 docx 权限"云文档权限未开同上，申请 docx → 重新发版"文档不存在"文档 token 错误或应用无访问权文档 → 右上角「分享」→ 添加应用"节点不存在"知识库节点 token 错误确认 node_token 正确
网络与连接错误#
错误信息原因解决方法Connection timeout网络超时确认服务器可访问 open.feishu.cn``HTTP 403IP 白名单限制飞书后台 → 安全设置 → 关闭 IP 白名单HTTP 429请求过快被限流添加延时： sleep 1 后重试SSL error证书问题确认服务器时间正确： date
七、凭证与权限体系详解#
凭证种类#
凭证有效期获取方式用途App Token（tenant_access_token）2小时，自动续期app_id + app_secret 自动换取消息/日历/通讯录/审批/多维表格/云盘User Access Token2小时OAuth 用户授权知识库/云文档搜索和读取
权限申请自查表（按功能）#
需要的功能必须申请的权限是否需重新发版发消息到群im:message✅获取群列表im:chat:read✅创建群聊im:chat✅日历读写calendar✅通讯录查询contact✅提交审批approval✅多维表格读写bitable:app✅电子表格读写sheets✅云盘文件管理drive✅知识库搜索/读取wiki✅ + User Token云文档搜索/读取docx✅ + User Token获取用户信息contact:user.id:readonly✅
八、调试与排障流程图#
text
工具调用报错
│
├─ FileNotFoundError / JSONDecodeError
│ → 检查 /workspace/.lark_tokens.json 是否存在、格式是否正确
│
├─ lark-mcp: command not found
│ → npm install -g @larksuite/lark-mcp
│
├─ 99991663（Token 无效）
│ → 重新确认 app_id 和 app_secret 是否正确
│
├─ 99991403（权限不足）
│ ├─ 应用权限未申请 → 飞书后台申请 + 发版
│ └─ 文档未分享给应用 → 文档右上角「分享」添加应用
│
├─ 99991700（不在群里）
│ → 手动把机器人拉入目标群
│
├─ 99991140（频率超限）
│ → 降低调用频率
│
└─ 无输出 / 超时
→ lark-mcp --help 确认可用性，重试
九、频率限制参考#
接口类型限制超过后大多数 API50次/秒收到 99991140，等待后重试知识库搜索5次/秒等待 1 秒再试发送消息50次/秒加 sleep(0.1) 控制频率创建日程10次/秒降低频率创建电子表格5次/分控制调用节奏批量发消息受单发限制叠加建议间隔发送
十、参考文件索引#
文件内容references/start-here.md快速入门，三分钟上手references/tools-index.md全部工具完整索引（60+ 接口）references/auth.md认证体系、双层权限模型详解references/errors.md完整错误码速查references/im.md消息与群组 API 详解references/drive.md云盘与文件 API 详解references/wiki.md知识库 API 详解references/docx.md云文档 API 详解references/sheets.md电子表格 API 详解references/bitable.md多维表格 API 详解references/board.md画板 API 详解references/contact.md通讯录 API 详解references/calendar.md日历 API 详解references/approval.md审批 API 详解
相关推荐
Gog
Ssteipetev1.0.0
Google Workspace 命令行工具，支持 Gmail、日历、云端硬盘、通讯录、表格和文档。
办公效率需 API Key
Word / DOCX
Iivangdavilav1.0.2
创建、检查和编辑 Microsoft Word 文档及 DOCX 文件，支持样式、编号、修订记录、表格、分节符及兼容性检查等功能。
办公效率
Excel / XLSX
Iivangdavilav1.0.2
创建、检查和编辑 Microsoft Excel 工作簿及 XLSX 文件，支持可靠的公式、日期、类型、格式、重算及模板保留功能。
办公效率
Nano Pdf
Ssteipetev1.0.0
使用nano-pdf CLI通过自然语言指令编辑PDF
办公效率
