{
  "markdown": "# FeiShuSkill\n\n> **一键安装 Feishu MCP，通过 MCP 控制飞书**\n>\n> 集成飞书（Feishu/Lark）服务的 AI Skill，让 AI 能够操作多维表格、文档、消息、群组等功能\n\n## 📋 目录\n\n- [项目简介](#-项目简介)\n- [功能特性](#-功能特性)\n- [环境要求](#-环境要求)\n- [安装](#-安装)\n- [配置飞书凭证与权限](#-配置飞书凭证与权限)\n- [快速开始](#-快速开始)\n- [用法示例](#-用法示例)\n- [高级配置（OAuth）](#-高级配置oauth)\n- [故障排查](#-故障排查)\n- [开发与贡献](#-开发与贡献)\n- [许可证](#-许可证)\n\n## 🌟 项目简介\n\nFeiShuSkill 是一个基于 [MCP（Model Context Protocol）](https://modelcontextprotocol.io/) 的 AI Skill，通过飞书官方 MCP 服务（`@larksuiteoapi/lark-mcp`）将 AI 与飞书开放平台连接，让你可以用自然语言直接控制飞书——查表格、发消息、搜文档、管群组，一句话搞定。\n\n**核心流程：**\n```\n你的自然语言指令 → AI（Claude 等） → Feishu MCP 服务 → 飞书开放平台 API\n```\n\n## ✨ 功能特性\n\n- **多维表格操作**：创建表格、查询/新增/修改/删除记录\n- **消息收发**：发送文本、富文本消息到群组或个人\n- **文档管理**：搜索文档、获取内容（需 OAuth）\n- **群组管理**：创建群组、管理成员、获取群信息\n- **权限控制**：添加协作者、设置访问权限\n- **联系人管理**：通过邮箱/手机号获取用户信息\n- **知识库操作**：搜索 Wiki、获取节点信息（需 OAuth）\n\n## 🖥️ 环境要求\n\n| 依赖 | 说明 |\n|------|------|\n| **Node.js ≥ 18**（含 `npx`） | 用于运行飞书 MCP 服务 |\n| **支持 MCP 的 AI 客户端** | Claude Desktop、Claude Code 等 |\n| **飞书企业账号** | 需有权限创建企业自建应用 |\n\n> 无需本地克隆本仓库——Skill 安装只需一条命令，MCP 服务通过 `npx` 自动拉取。\n\n## 📦 安装\n\n### 一键安装（推荐）\n\n使用 [OpenSkills](https://github.com/openskills/openskills) 一键完成 Skill 安装：\n\n```bash\nnpm i -g openskills\nopenskills install whatevertogo/FeiShuSkill\n```\n\n按照提示填写你的飞书 `App ID` 和 `App Secret`，安装程序会自动写入 MCP 配置。\n\n---\n\n### 手动安装：Claude Desktop\n\n1. 在 Claude Desktop 配置文件中添加 MCP 服务器（详见[配置章节](#-配置飞书凭证与权限)）。\n\n2. 将本项目的 `lark-mcp/SKILL.md` 复制到 skills 文件夹：\n   - macOS：`~/Library/Application Support/Claude/skills/`\n   - Windows：`%APPDATA%\\Claude\\skills\\`\n   - Linux：`~/.config/Claude/skills/`\n\n3. 重启 Claude Desktop。\n\n---\n\n### 手动安装：Claude Code\n\n```bash\n# 复制 Skill 文档\ncp lark-mcp/SKILL.md ~/.claude/skills/lark-mcp.md\n```\n\n然后按[配置章节](#-配置飞书凭证与权限)完成 MCP 服务器配置。\n\n## ⚙️ 配置飞书凭证与权限\n\n### 第一步：获取飞书应用凭证\n\n1. 访问 [飞书开放平台](https://open.feishu.cn/app)\n2. 创建一个**企业自建应用**\n3. 在「凭证与基础信息」中获取：\n   - `App ID`（以 `cli_` 开头）\n   - `App Secret`\n\n### 第二步：添加应用权限\n\n在「权限管理」中开启所需权限（按需添加）：\n\n| 权限标识 | 用途 |\n|----------|------|\n| `bitable:app` | 多维表格读写 |\n| `im:message:send_as_bot` | 发送消息 |\n| `im:chat` | 群组管理 |\n| `docx:document` | 文档读写 |\n| `drive:drive` | 云空间 |\n| `contact:user.id:readonly` | 查询用户 ID |\n| `wiki:wiki:readonly` | 知识库查询 |\n\n### 第三步：配置 MCP 服务器\n\n在你的 AI 客户端配置文件中（如 Claude Desktop 的 `claude_desktop_config.json`）添加：\n\n```json\n{\n  \"mcpServers\": {\n    \"lark-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\", \"@larksuiteoapi/lark-mcp\", \"mcp\",\n        \"-a\", \"<your_app_id>\",\n        \"-s\", \"<your_app_secret>\"\n      ]\n    }\n  }\n}\n```\n\n将 `<your_app_id>` 和 `<your_app_secret>` 替换为实际值。\n\n> 💡 如需搜索文档或知识库，请参阅[高级配置（OAuth）](#-高级配置oauth)章节。\n\n## 🚀 快速开始\n\n配置完成后，直接向 AI 发出自然语言指令，AI 会自动调用相应的飞书 MCP 工具：\n\n**查询多维表格：**\n```\n请查询飞书多维表格 appXXXXX 中，状态为\"进行中\"的所有记录\n```\n\n**发送群消息：**\n```\n向\"项目通知群\"发送消息：\"本周任务已更新，请查收\"\n```\n\n**搜索文档：**\n```\n搜索包含\"Q4 季度报告\"的飞书文档\n```\n\n### 创建项目管理表格\n\n```\n创建一个项目管理表格，包含任务名称、负责人、状态、截止日期字段\n```\n\nAI 将调用 `bitable_v1_app_create` → `bitable_v1_appTable_create` → `bitable_v1_appTableField_create`，并使用 `useUAT: true`（用户身份）确保你可以直接访问。\n\n### 批量更新记录\n\n```\n将表格 tblXXXXX 中状态为\"待处理\"的记录更新为\"进行中\"\n```\n\nAI 先调用 `bitable_v1_appTableRecord_search` 查询符合条件的记录，再逐条调用 `bitable_v1_appTableRecord_update` 批量更新。\n\n### 生成周报并发送\n\n```\n查询本周已完成的任务，整理成报告发送到项目群 oc_XXXXX\n```\n\nAI 查询记录 → 整理数据 → 调用 `im_v1_message_create` 发送富文本消息。\n\n### 获取各类 ID\n\n从 URL 直接读取是最快的方式：\n\n```\n多维表格：https://xxx.feishu.cn/base/appXXXXX?table=tblXXXXX\n                                    ↑app_token      ↑table_id\n\n文档：    https://xxx.feishu.cn/docx/doxcXXXXX\n                                      ↑document_id\n```\n\n或让 AI 帮你查询：\n```\n列出我有权限访问的所有多维表格\n列出我所在的所有群组\n```\n\n## 🔐 高级配置（OAuth）\n\n搜索文档（`docx_builtin_search`）和搜索知识库（`wiki_v1_node_search`）需要用户令牌，必须同时配置 `--oauth` 和 `--token-mode user_access_token`：\n\n**1. 登录获取用户令牌：**\n```bash\nnpx -y @larksuiteoapi/lark-mcp login -a <your_app_id> -s <your_app_secret>\n```\n\n**2. 更新 MCP 配置：**\n```json\n{\n  \"mcpServers\": {\n    \"lark-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\", \"@larksuiteoapi/lark-mcp\", \"mcp\",\n        \"-a\", \"<your_app_id>\",\n        \"-s\", \"<your_app_secret>\",\n        \"--oauth\",\n        \"--token-mode\", \"user_access_token\"\n      ]\n    }\n  }\n}\n```\n\n**3. 在飞书开放平台配置重定向 URL：**\n\n「应用」→「安全设置」→「重定向 URL」中添加：\n```\nhttp://localhost:3000/callback\n```\n\n**4. 重启 AI 客户端。**\n\n| 场景 | 无 OAuth | 有 OAuth |\n|------|:-------:|:-------:|\n| 多维表格操作 | ✅ | ✅ |\n| 发送消息 | ✅ | ✅ |\n| 搜索文档/知识库 | ❌ | ✅ |\n| 资源创建者为当前用户 | ❌ | ✅ |\n\n## ❓ 故障排查\n\n### AI 提示\"工具未找到\"\n\n- MCP 服务未启动——检查配置文件中的 `mcpServers` 是否正确\n- 是否mcp配置中加入了-t等，他会限制工具数目和内容\n- 重启 AI 客户端\n\n### 错误码 99991663\n\n仅配置 `--oauth` 不够，必须同时加 `--token-mode user_access_token`，详见[高级配置](#-高级配置oauth)。\n\n### `redirect_uri_mismatch` 错误\n\n在飞书开放平台的应用安全设置中添加重定向 URL：`http://localhost:3000/callback`\n\n### 权限不足（403）\n\n检查飞书应用的「权限管理」，确认已开启对应权限并发布版本。\n\n### 创建的资源无法访问\n\n使用租户身份（`useUAT: false`，默认）创建的资源，创建者为应用而非用户。告知 AI\"请使用用户身份（useUAT: true）创建\"。\n\n### 消息发送失败\n\n- 确认机器人已加入目标群组\n- 群组用 `receive_id_type: chat_id`，个人用 `open_id`\n\n更多错误码参考 [lark-mcp/reference/troubleshooting.md](lark-mcp/reference/troubleshooting.md)。\n\n## 🤝 开发与贡献\n\n欢迎提交 Issue 反馈问题，或通过 Pull Request 改进文档与示例：\n\n1. Fork 本仓库\n2. 创建分支：`git checkout -b feat/your-feature`\n3. 提交修改：`git commit -m 'feat: 描述你的改动'`\n4. 推送并发起 PR\n\n**文档结构：**\n\n| 文件 | 说明 |\n|------|------|\n| `lark-mcp/SKILL.md` | Skill 核心技术文档（工具列表、参数、工作流） |\n| `lark-mcp/plugin.json` | MCP 服务器配置模板 |\n| `lark-mcp/reference/` | 各功能参考文档 |\n| `lark-mcp/examples/` | 多维表格查询、消息格式示例 |\n\n## 📄 许可证\n\n[MIT License](LICENSE) © 2026 whatevertogo\n\n## 🙏 致谢\n\n- [飞书开放平台](https://open.feishu.cn/)\n- [@larksuiteoapi/lark-mcp](https://www.npmjs.com/package/@larksuiteoapi/lark-mcp)\n- [MCP 协议](https://modelcontextprotocol.io/)\n",
  "bytes": 5510,
  "sha": "392fa4e97f23a7d7241f5e5ee03513522c3f9201811dafa70bcf976cd0115d0f",
  "repo_slug": "whatevertogo/feishuskill",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_whatevertogo_feishuskill_lark_mcp_ee16385b/readme"
}