FeiShuSkill

一键安装 Feishu MCP，通过 MCP 控制飞书

集成飞书（Feishu/Lark）服务的 AI Skill，让 AI 能够操作多维表格、文档、消息、群组等功能

📋 目录

• 项目简介
• 功能特性
• 环境要求
• 安装
• 配置飞书凭证与权限
• 快速开始
• 用法示例
• 高级配置（OAuth）
• 故障排查
• 开发与贡献
• 许可证

🌟 项目简介

FeiShuSkill 是一个基于 MCP（Model Context Protocol） 的 AI Skill，通过飞书官方 MCP 服务（@larksuiteoapi/lark-mcp）将 AI 与飞书开放平台连接，让你可以用自然语言直接控制飞书——查表格、发消息、搜文档、管群组，一句话搞定。

核心流程：

你的自然语言指令 → AI（Claude 等） → Feishu MCP 服务 → 飞书开放平台 API

✨ 功能特性

• 多维表格操作：创建表格、查询/新增/修改/删除记录
• 消息收发：发送文本、富文本消息到群组或个人
• 文档管理：搜索文档、获取内容（需 OAuth）
• 群组管理：创建群组、管理成员、获取群信息
• 权限控制：添加协作者、设置访问权限
• 联系人管理：通过邮箱/手机号获取用户信息
• 知识库操作：搜索 Wiki、获取节点信息（需 OAuth）

🖥️ 环境要求

依赖	说明
Node.js ≥ 18（含 npx）	用于运行飞书 MCP 服务
支持 MCP 的 AI 客户端	Claude Desktop、Claude Code 等
飞书企业账号	需有权限创建企业自建应用

无需本地克隆本仓库——Skill 安装只需一条命令，MCP 服务通过 npx 自动拉取。

📦 安装

一键安装（推荐）

使用 OpenSkills 一键完成 Skill 安装：

npm i -g openskills
openskills install whatevertogo/FeiShuSkill

按照提示填写你的飞书 App ID 和 App Secret，安装程序会自动写入 MCP 配置。

---

手动安装：Claude Desktop

1. 在 Claude Desktop 配置文件中添加 MCP 服务器（详见配置章节）。

2. 将本项目的 lark-mcp/SKILL.md 复制到 skills 文件夹：

   • macOS：~/Library/Application Support/Claude/skills/
   • Windows：%APPDATA%\Claude\skills\
   • Linux：~/.config/Claude/skills/

3. 重启 Claude Desktop。

---

手动安装：Claude Code

# 复制 Skill 文档
cp lark-mcp/SKILL.md ~/.claude/skills/lark-mcp.md

然后按配置章节完成 MCP 服务器配置。

⚙️ 配置飞书凭证与权限

第一步：获取飞书应用凭证

1. 访问 飞书开放平台
2. 创建一个企业自建应用
3. 在「凭证与基础信息」中获取：
   • App ID（以 cli_ 开头）
   • App Secret

第二步：添加应用权限

在「权限管理」中开启所需权限（按需添加）：

权限标识	用途
bitable:app	多维表格读写
im:message:send_as_bot	发送消息
im:chat	群组管理
docx:document	文档读写
drive:drive	云空间
contact:user.id:readonly	查询用户 ID
wiki:wiki:readonly	知识库查询

第三步：配置 MCP 服务器

在你的 AI 客户端配置文件中（如 Claude Desktop 的 claude_desktop_config.json）添加：

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

将 <your_app_id> 和 <your_app_secret> 替换为实际值。

💡 如需搜索文档或知识库，请参阅高级配置（OAuth）章节。

🚀 快速开始

配置完成后，直接向 AI 发出自然语言指令，AI 会自动调用相应的飞书 MCP 工具：

查询多维表格：

请查询飞书多维表格 appXXXXX 中，状态为"进行中"的所有记录

发送群消息：

向"项目通知群"发送消息："本周任务已更新，请查收"

搜索文档：

搜索包含"Q4 季度报告"的飞书文档

创建项目管理表格

创建一个项目管理表格，包含任务名称、负责人、状态、截止日期字段

AI 将调用 bitable_v1_app_create → bitable_v1_appTable_create → bitable_v1_appTableField_create，并使用 useUAT: true（用户身份）确保你可以直接访问。

批量更新记录

将表格 tblXXXXX 中状态为"待处理"的记录更新为"进行中"

AI 先调用 bitable_v1_appTableRecord_search 查询符合条件的记录，再逐条调用 bitable_v1_appTableRecord_update 批量更新。

生成周报并发送

查询本周已完成的任务，整理成报告发送到项目群 oc_XXXXX

AI 查询记录 → 整理数据 → 调用 im_v1_message_create 发送富文本消息。

获取各类 ID

从 URL 直接读取是最快的方式：

多维表格：https://xxx.feishu.cn/base/appXXXXX?table=tblXXXXX
                                    ↑app_token      ↑table_id

文档：    https://xxx.feishu.cn/docx/doxcXXXXX
                                      ↑document_id

或让 AI 帮你查询：

列出我有权限访问的所有多维表格
列出我所在的所有群组

🔐 高级配置（OAuth）

搜索文档（docx_builtin_search）和搜索知识库（wiki_v1_node_search）需要用户令牌，必须同时配置 --oauth 和 --token-mode user_access_token：

1. 登录获取用户令牌：

npx -y @larksuiteoapi/lark-mcp login -a <your_app_id> -s <your_app_secret>

2. 更新 MCP 配置：

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

3. 在飞书开放平台配置重定向 URL：

「应用」→「安全设置」→「重定向 URL」中添加：

http://localhost:3000/callback

4. 重启 AI 客户端。

场景	无 OAuth	有 OAuth
多维表格操作	✅	✅
发送消息	✅	✅
搜索文档/知识库	❌	✅
资源创建者为当前用户	❌	✅

❓ 故障排查

AI 提示"工具未找到"

• MCP 服务未启动——检查配置文件中的 mcpServers 是否正确
• 是否mcp配置中加入了-t等，他会限制工具数目和内容
• 重启 AI 客户端

错误码 99991663

仅配置 --oauth 不够，必须同时加 --token-mode user_access_token，详见高级配置。

redirect_uri_mismatch 错误

在飞书开放平台的应用安全设置中添加重定向 URL：http://localhost:3000/callback

权限不足（403）

检查飞书应用的「权限管理」，确认已开启对应权限并发布版本。

创建的资源无法访问

使用租户身份（useUAT: false，默认）创建的资源，创建者为应用而非用户。告知 AI"请使用用户身份（useUAT: true）创建"。

消息发送失败

• 确认机器人已加入目标群组
• 群组用 receive_id_type: chat_id，个人用 open_id

更多错误码参考 lark-mcp/reference/troubleshooting.md。

🤝 开发与贡献

欢迎提交 Issue 反馈问题，或通过 Pull Request 改进文档与示例：

1. Fork 本仓库
2. 创建分支：git checkout -b feat/your-feature
3. 提交修改：git commit -m 'feat: 描述你的改动'
4. 推送并发起 PR

文档结构：

文件	说明
lark-mcp/SKILL.md	Skill 核心技术文档（工具列表、参数、工作流）
lark-mcp/plugin.json	MCP 服务器配置模板
lark-mcp/reference/	各功能参考文档
lark-mcp/examples/	多维表格查询、消息格式示例

📄 许可证

MIT License © 2026 whatevertogo

🙏 致谢

• 飞书开放平台
• @larksuiteoapi/lark-mcp
• MCP 协议