skills/whatevertogo__feishuskill
1
0
Fork 0
mirror of https://github.com/whatevertogo/FeiShuSkill.git synced 2026-09-14 14:41:00 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #2 from whatevertogo/copilot/update-readme-for-feishu-mcp

Browse Source 
docs: 更新 README（Feishu MCP 一键安装与控制飞书）
This commit is contained in:
whatevertogo
2026-03-22 00:57:54 +08:00
committed by GitHub
parent c2c64f0a21 f81791d5c2
commit 5eff8e8e90
1 changed files with 207 additions and 257 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+207 -257
View File
@@ -1,349 +1,299 @@
# FeiShuSkill
> **一键安装 Feishu MCP，通过 MCP 控制飞书**
>
> 集成飞书（Feishu/Lark）服务的 AI Skill，让 AI 能够操作多维表格、文档、消息、群组等功能
## 📋 目录
- [前置准备（重要）](#-前置准备重要)
- [项目简介](#-项目简介)
- [功能特性](#-功能特性)
- [安装方式](#-安装方式)
- [环境要求](#-环境要求)
- [安装](#-安装)
- [配置飞书凭证与权限](#-配置飞书凭证与权限)
- [快速开始](#-快速开始)
- [核心概念](#-核心概念)
- [使用示例](#-使用示例)
- [常见问题](#-常见问题)
- [相关文档](#-相关文档)
- [用法示例](#-用法示例)
- [高级配置（OAuth）](#-高级配置oauth)
- [故障排查](#-故障排查)
- [开发与贡献](#-开发与贡献)
- [许可证](#-许可证)
## ⚠️ 前置准备（重要）
## 🌟 项目简介
### 第一步：配置飞书 MCP 服务
FeiShuSkill 是一个基于 [MCP（Model Context Protocol）](https://modelcontextprotocol.io/) 的 AI Skill，通过飞书官方 MCP 服务（`@larksuiteoapi/lark-mcp`）将 AI 与飞书开放平台连接，让你可以用自然语言直接控制飞书——查表格、发消息、搜文档、管群组，一句话搞定。
**在使用本 Skill 之前，您必须先完成飞书 MCP 服务的安装和配置。**
请完整阅读并按照官方文档操作：
👉 **[飞书 MCP 集成安装指南](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/mcp_integration/mcp_installation)**
该指南将教您：
1. 创建飞书应用并获取必要的凭证
2. 配置 MCP 服务器
3. 安装和启动 MCP 服务
4. 验证服务是否正常运行
**为什么要先配置 MCP 服务？**
- MCP（Model Context Protocol）是连接 AI 和飞书服务的桥梁
- 本 Skill 基于 MCP 服务提供的工具来操作飞书
- 没有 MCP 服务，AI 将无法调用任何飞书功能
完成 MCP 服务配置后，使用本 Skill 将获得以下效果：
- ✅ AI 能够理解您的飞书操作需求
- ✅ 自动调用正确的 MCP 工具
- ✅ 智能处理参数和错误
- ✅ 提供更流畅的交互体验
**核心流程：**
```
你的自然语言指令 → AI（Claude 等） → Feishu MCP 服务 → 飞书开放平台 API
```
## ✨ 功能特性
- **多维表格操作**：创建表格、查询记录、增删改数据
- **消息收发**：发送文本、富文本、卡片消息到群组或个人
- **文档管理**：搜索文档、获取内容、导入导出
- **多维表格操作**：创建表格、查询/新增/修改/删除记录
- **消息收发**：发送文本、富文本消息到群组或个人
- **文档管理**：搜索文档、获取内容（需 OAuth）
- **群组管理**：创建群组、管理成员、获取群信息
- **权限控制**：添加协作者、设置访问权限
- **联系人管理**：通过邮箱/手机号获取用户信息
- **知识库操作**：搜索 Wiki、获取节点信息
- **知识库操作**：搜索 Wiki、获取节点信息（需 OAuth）
## 📦 安装方式
## 🖥️ 环境要求
### 方式 1：Claude Desktop（推荐）
| 依赖 | 说明 |
|------|------|
| **Node.js ≥ 18**（含 `npx`） | 用于运行飞书 MCP 服务 |
| **支持 MCP 的 AI 客户端** | Claude Desktop、Claude Code 等 |
| **飞书企业账号** | 需有权限创建企业自建应用 |
1. 找到 Claude Desktop 的 skills 文件夹：
- Windows: `%APPDATA%\Claude\skills\`
- macOS: `~/Library/Application Support/Claude/skills/`
- Linux: `~/.config/Claude/skills/`
> 无需本地克隆本仓库——Skill 安装只需一条命令，MCP 服务通过 `npx` 自动拉取。
2. 将本项目的 `SKILL.md` 复制到 skills 文件夹
## 📦 安装
3. 重启 Claude Desktop
### 一键安装（推荐）
### 方式 2：Claude Code
使用 [OpenSkills](https://github.com/openskills/openskills) 一键完成 Skill 安装：
```bash
# 将 SKILL.md 复制到 Claude Code 的 skills 目录
cp SKILL.md ~/.claude/skills/lark-mcp.md
```
### 方式 3：给Claude Code用
```bash
npm i -g openskills
```
```bash
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
```bash
# 复制 Skill 文档
cp lark-mcp/SKILL.md ~/.claude/skills/lark-mcp.md
```
然后按[配置章节](#-配置飞书凭证与权限)完成 MCP 服务器配置。
## ⚙️ 配置飞书凭证与权限
### 第一步：获取飞书应用凭证
1. 访问 [飞书开放平台](https://open.feishu.cn/app)
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`）添加：
```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）](#-高级配置oauth)章节。
## 🚀 快速开始
### 前提条件检查
配置完成后，直接向 AI 发出自然语言指令，AI 会自动调用相应的飞书 MCP 工具：
在使用前，请确认：
- [x] 已按照[官方文档](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/mcp_integration/mcp_installation)配置好 MCP 服务
- [x] MCP 服务正在运行
- [x] 已创建飞书应用并获取必要的权限
- [x] 已安装本 Skill 到 AI 工具中
### 第一个任务：查询多维表格
向 AI 提问：
**查询多维表格：**
```
请查询飞书多维表格中状态为"进行中"的所有记录
请查询飞书多维表格 appXXXXX 中，状态为"进行中"的所有记录
```
AI 将自动：
1. 调用 `bitable_v1_appTableRecord_search` 工具
2. 使用正确的参数格式
3. 处理查询结果
4. 以友好的方式展示数据
### 第二个任务：发送群消息
向 AI 提问：
**发送群消息：**
```
向"项目通知群"发送消息："本周任务已更新，请查收"
```
AI 将自动：
1. 查找群组的 chat_id
2. 调用 `im_v1_message_create` 工具
3. 使用正确的消息格式
4. 确认发送状态
## 📚 核心概念
### 1. 工具命名规范
所有 MCP 工具都以 `mcp__lark-mcp__` 开头：
**搜索文档：**
```
mcp__lark-mcp__bitable_v1_appTableRecord_search
↑ ↑
服务器前缀 工具名称
搜索包含"Q4 季度报告"的飞书文档
```
### 2. 身份类型（重要）
## 💡 用法示例
- **useUAT: true** - 用户身份
- 创建的资源，创建者是当前用户
- 用户可以直接访问
- 适合大多数操作
所有工具均以 `mcp__lark-mcp__` 为前缀，由 AI 自动调用，无需手动输入工具名称。
- **useUAT: false** - 租户身份（默认）
- 创建的资源，创建者是应用
- 可能需要额外配置权限
- 适合后台自动化任务
### 创建项目管理表格
### 3. ID 类型
| ID 类型 | 用途 | 示例 |
|---------|------|------|
| `app_token` | 多维表格应用 ID | `appxxxxx` |
| `table_id` | 表格 ID | `tblxxxxx` |
| `record_id` | 记录 ID | `recxxxxx` |
| `open_id` | 用户 ID | `ou_xxxxx` |
| `chat_id` | 群组 ID | `oc_xxxxx` |
| `document_id` | 文档 ID | `doxcxxxx` |
### 4. 参数结构
```yaml
path: # URL 路径参数（必需）
app_token: "xxx"
table_id: "xxx"
params: # URL 查询参数（可选）
user_id_type: "open_id"
page_size: 20
data: # 请求体（可选）
fields: {...}
useUAT: true # 身份类型（可选）
```
## 💡 使用示例
### 示例 1：创建项目管理表格
向 AI 提问：
```
创建一个项目管理表格，包含任务名称、负责人、状态、截止日期字段
```
AI 将：
1. 使用 `bitable_v1_app_create` 创建 Base 应用（useUAT: true）
2. 使用 `bitable_v1_appTable_create` 创建表格
3. 定义字段：文本、人员、单选、日期
4. 确保创建后您可以直接访问
AI 将调用 `bitable_v1_app_create` → `bitable_v1_appTable_create` → `bitable_v1_appTableField_create`，并使用 `useUAT: true`（用户身份）确保你可以直接访问。
### 示例 2：批量更新记录
### 批量更新记录
向 AI 提问：
```
将表格中状态为"待处理"的记录更新为"进行中"
将表格 tblXXXXX 中状态为"待处理"的记录更新为"进行中"
```
AI 将：
1. 先查询符合条件的记录
2. 逐个调用 `bitable_v1_appTableRecord_update`
3. 更新状态字段
4. 汇总更新结果
AI 先调用 `bitable_v1_appTableRecord_search` 查询符合条件的记录，再逐条调用 `bitable_v1_appTableRecord_update` 批量更新。
### 示例 3：定时报告生成
### 生成周报并发送
向 AI 提问：
```
查询本周已完成的任务，生成报告并发送到项目群
查询本周已完成的任务，整理成报告发送到项目群 oc_XXXXX
```
AI 将：
1. 查询状态为"已完成"的记录
2. 整理数据生成报告
3. 使用 `im_v1_message_create` 发送富文本消息
4. 确认发送成功
AI 查询记录 → 整理数据 → 调用 `im_v1_message_create` 发送富文本消息。
### 示例 4：文档搜索与整理
### 获取各类 ID
从 URL 直接读取是最快的方式：
向 AI 提问：
```
搜索包含"Q4 季度报告"的文档，列出所有找到的文档
多维表格：https://xxx.feishu.cn/base/appXXXXX?table=tblXXXXX
↑app_token ↑table_id
文档： https://xxx.feishu.cn/docx/doxcXXXXX
↑document_id
```
AI 将：
1. 使用 `docx_builtin_search` 搜索文档
2. 解析搜索结果
3. 提取文档标题、链接、创建时间
4. 整理成清单展示
## ❓ 常见问题
### Q1: AI 提示"工具未找到"
**原因**：MCP 服务未正确配置
**解决**：
1. 检查 MCP 服务是否正在运行
2. 确认工具名称格式：`mcp__lark-mcp__xxx`
3. 重启 AI 应用
### Q2: 创建的资源无法访问
**原因**：使用了租户身份创建资源
**解决**：
向 AI 说明："请使用用户身份（useUAT: true）创建"
或直接告诉 AI："创建一个用户可访问的表格"
### Q3: 权限不足错误
**原因**：飞书应用未获得相应权限
**解决**：
1. 检查飞书开放平台的应用权限配置
2. 确认已授予以下权限：
- `bitable:app` - 多维表格
- `im:message` - 消息
- `im:chat` - 群组
- `docs:docs` - 文档
- `drive:drive` - 云空间
### Q4: 消息发送失败
**原因**：机器人未在群组中或无发送权限
**解决**：
1. 确认机器人已加入群组
2. 确认机器人在群组中可以发言
3. 检查 receive_id_type 是否正确（群组用 chat_id，用户用 open_id）
### Q5: 如何获取各种 ID？
**方法 1：从 URL 获取**
或让 AI 帮你查询：
```
多维表格 URL：
https://xxx.feishu.cn/base/appxxxxx?table=tblxxxxx
↑app_token ↑table_id
文档 URL：
https://xxx.feishu.cn/docx/doxcxxxx
↑document_id
列出我有权限访问的所有多维表格
列出我所在的所有群组
```
**方法 2：让 AI 帮忙查询**
```
"列出我有权限访问的所有多维表格"
"搜索'项目报告'相关的文档"
## 🔐 高级配置（OAuth）
搜索文档（`docx_builtin_search`）和搜索知识库（`wiki_v1_node_search`）需要用户令牌，必须同时配置 `--oauth` 和 `--token-mode user_access_token`：
**1. 登录获取用户令牌：**
```bash
npx -y @larksuiteoapi/lark-mcp login -a <your_app_id> -s <your_app_secret>
```
**方法 3：使用 MCP 工具**
- `bitable_v1_appTable_list` - 列出所有表格
- `docx_builtin_search` - 搜索文档
- `im_v1_chat_list` - 列出所有群组
**2. 更新 MCP 配置：**
```json
{
"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：**
### 技巧 1：使用工作流模板
「应用」→「安全设置」→「重定向 URL」中添加：
```
http://localhost:3000/callback
```
在本 Skill 的详细文档中，提供了多个完整的工作流：
- 创建多维表格并添加记录
- 查询表格并发送消息
- 搜索文档并获取内容
**4. 重启 AI 客户端。**
参考 [SKILL.md](SKILL.md) 中的"核心工作流"章节。
| 场景 | 无 OAuth | 有 OAuth |
|------|:-------:|:-------:|
| 多维表格操作 | ✅ | ✅ |
| 发送消息 | ✅ | ✅ |
| 搜索文档/知识库 | ❌ | ✅ |
| 资源创建者为当前用户 | ❌ | ✅ |
### 技巧 2：错误处理
## ❓ 故障排查
当遇到错误时，AI 会：
1. 分析错误信息
2. 查找可能的原因
3. 提供解决方案
4. 尝试重新执行
### AI 提示"工具未找到"
参考 [SKILL.md](SKILL.md) 中的"常见错误排查"章节。
- MCP 服务未启动——检查配置文件中的 `mcpServers` 是否正确
- 工具名须以 `mcp__lark-mcp__` 开头（用连字符，不是下划线）
- 重启 AI 客户端
### 技巧 3：参数校验
### 错误码 99991663
在执行前，AI 会检查：
- [ ] 服务器名称正确
- [ ] path 参数完整
- [ ] content 是 JSON 字符串
- [ ] value 是数组格式
- [ ] ID 类型匹配
仅配置 `--oauth` 不够，必须同时加 `--token-mode user_access_token`，详见[高级配置](#-高级配置oauth)。
## 📖 相关文档
### `redirect_uri_mismatch` 错误
- **[SKILL.md](SKILL.md)** - 完整的 Skill 技术文档
- 详细的工具说明
- 参数结构解释
- 工作流示例
- 错误排查指南
在飞书开放平台的应用安全设置中添加重定向 URL：`http://localhost:3000/callback`
- **[examples/](examples/)** - 使用示例
- 多维表格查询示例
- 消息格式示例
### 权限不足（403）
- **[reference/](reference/)** - 功能参考
- 多维表格操作指南
- 消息发送指南
- 文档操作指南
- 群组管理指南
- 权限管理指南
检查飞书应用的「权限管理」，确认已开启对应权限并发布版本。
## 🤝 贡献
### 创建的资源无法访问
欢迎提交 Issue 和 Pull Request！
使用租户身份（`useUAT: false`，默认）创建的资源，创建者为应用而非用户。告知 AI"请使用用户身份（useUAT: true）创建"。
### 消息发送失败
- 确认机器人已加入目标群组
- 群组用 `receive_id_type: chat_id`，个人用 `open_id`
更多错误码参考 [lark-mcp/reference/troubleshooting.md](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/` | 多维表格查询、消息格式示例 |
## 📄 许可证
[License](LICENSE)
[MIT License](LICENSE) © 2026 whatevertogo
## 🙏 致谢
- [飞书开放平台](https://open.feishu.cn/)
- [Claude Code](https://code.anthropic.com/)
- MCP 协议贡献者
---
**注意**：本 Skill 需要配合飞书 MCP 服务使用。请先完成 [MCP 服务配置](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/mcp_integration/mcp_installation) 再使用本 Skill。
- [@larksuiteoapi/lark-mcp](https://www.npmjs.com/package/@larksuiteoapi/lark-mcp)
- [MCP 协议](https://modelcontextprotocol.io/)