# 飞书 MCP 服务器（增强版）

[![npm version](https://img.shields.io/npm/v/feishu-docx-mcp?color=blue&label=npm)](https://www.npmjs.com/package/feishu-docx-mcp)
[![MIT License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)

> **本项目基于 [cso1z/Feishu-MCP](https://github.com/cso1z/Feishu-MCP) 开源项目改造而来**，在原有功能基础上进行了大量增强，主要面向 Claude Code 等 AI 编码工具的深度集成场景。感谢原作者的出色工作。

为 [Cursor](https://cursor.sh/)、[Windsurf](https://codeium.com/windsurf)、[Cline](https://cline.bot/)、**[Claude Code](https://claude.ai/code)** 和其他 AI 驱动的编码工具提供访问、编辑和结构化处理飞书文档的能力，基于 [Model Context Protocol](https://modelcontextprotocol.io/introduction) 服务器实现。

本项目让 AI 编码工具能够直接获取和理解飞书文档的结构化内容，显著提升文档处理的智能化和效率。

**完整覆盖飞书文档的真实使用流程，助你高效利用文档资源：**
1. **文件夹目录获取**：快速获取和浏览飞书文档文件夹下的所有文档，便于整体管理和查找。
2. **内容获取与理解**：支持 Markdown、大纲、关键字搜索等多维度内容读取，AI 能精准理解文档上下文。
3. **智能创建与编辑**：可自动创建新文档、批量生成和编辑内容，支持 Markdown 级别的章节替换与追加。
4. **高效检索与搜索**：内置关键字搜索，帮助你在大量文档中迅速找到目标信息。

---

## 🆕 相对原版的改造内容

本 fork 在原版基础上新增了以下功能，主要提升 AI 对文档的**深度理解**和**高效编辑**能力：

### 1. Markdown 输出与 Feishu Link Tags
重构文档读取输出格式，引入 `<feishu:image>`、`<feishu:whiteboard>` 等语义标签，替代原来的纯文本/块 JSON 输出。AI 可直接获得结构化的 Markdown，保留图片、白板、Mermaid 等非文本元素的引用。

### 2. Extra 富文本增强区
在文档读取结果末尾附加 `<extra>` 区块，包含：
- **图片 AI 描述**：自动调用视觉模型分析文档中的图片内容（需配置 `IMAGE_AI_PROVIDER`）
- **群聊卡片信息**：解析 `chat_card` 块，输出群名称与描述
- **@ 提及用户**：解析 `mention_user` 元素，输出用户显示名

### 3. 白板转 PlantUML
自动将飞书文档中的白板内容转换为 PlantUML 格式（支持流程图、时序图、状态图、类图、思维导图等），AI 可直接理解白板中的图形逻辑。

### 4. 多维表格（Bitable）记录读取
支持读取嵌入式多维表格的记录数据，在 extra 区块中输出字段与行内容。

### 5. Markdown 级别文档编辑（新增两个工具）
- **`append_markdown_to_document`**：将 Markdown 内容追加到文档末尾或指定位置
- **`replace_feishu_document_section`**：按标题定位章节，整体替换为新 Markdown 内容；保留图片/文件引用（`feishu://media/TOKEN`）

### 6. 文件附件上传（新增工具）
- **`upload_file_to_document`**：上传本地或远程文件到文档，支持 PDF 预览模式

### 7. 块索引精准查询（新增两个工具）
- **`lookup_block`**：按语义 key 查询块的完整 JSON 数据
- **`lookup_block_index`**：获取块的父 ID、兄弟位置，用于精准插入/删除

### 8. 工具精简
移除了以下工具，避免冗余调用：
- `get_feishu_whiteboard_content`（功能已内置到 extra 区块）
- `get_feishu_image_resource`（功能已内置到 extra 区块）
- `copy_feishu_document`（实验性功能，已下线）

### 9. Claude Code 配套 Skill
提供 `feishu-mcp-workflows` skill，涵盖 19 个工具的完整工作流与最佳实践，专为 Claude Code 用户优化（见下方 [配套 Skill](#-配套-claude-code-skill)）。

---

> ⭐ **Star 本项目，第一时间获取最新功能和重要更新！**

---

## 🛠️ 工具功能详情（19 个工具）

> npm 包名：[`feishu-docx-mcp`](https://www.npmjs.com/package/feishu-docx-mcp)

| 功能类别 | 工具名称 | 描述 | 状态 |
|---------|--------|------|------|
| **文档管理** | `create_feishu_document` | 创建新的飞书文档（支持 Drive 文件夹和 Wiki 空间） | ✅ |
| | `get_feishu_document_info` | 获取文档基本信息；Wiki 链接转文档 ID | ✅ |
| | `get_feishu_document_blocks` | 获取文档内容（Markdown/大纲/关键字搜索模式） | ✅ |
| **Markdown 编辑** 🆕 | `append_markdown_to_document` | 将 Markdown 内容追加到文档末尾或指定位置 | ✅ |
| | `replace_feishu_document_section` | 按标题定位章节，整体替换为新 Markdown | ✅ |
| **块级编辑** | `batch_create_feishu_blocks` | 批量创建多个块（文本/标题/代码/列表/图片/Mermaid/白板/表格） | ✅ |
| | `update_feishu_block_text` | 更新已有块的文本内容和样式 | ✅ |
| | `delete_feishu_document_blocks` | 删除文档块 | ✅ |
| **块索引查询** 🆕 | `lookup_block` | 按语义 key 查询块的完整 JSON 数据 | ✅ |
| | `lookup_block_index` | 获取块的父 ID 和兄弟位置，用于精准插入/删除 | ✅ |
| **图片 & 文件** | `upload_and_bind_image_to_block` | 上传本地或远程图片并绑定到图片块 | ✅ |
| 🆕 | `upload_file_to_document` | 上传文件附件到文档（支持 PDF 预览） | ✅ |
| **表格** | `create_feishu_table` | 创建多行列表格，单元格支持多种块类型 | ✅ |
| **白板** | `fill_whiteboard_with_plantuml` | 向白板块填充 PlantUML 或 Mermaid 图表 | ✅ |
| **文件夹管理** | `get_feishu_root_folder_info` | 获取根文件夹、知识库空间列表 | ✅ |
| | `get_feishu_folder_files` | 获取文件夹/Wiki 节点下的文件列表 | ✅ |
| | `create_feishu_folder` | 创建新文件夹 | ✅ |
| **搜索** | `search_feishu_documents` | 关键字搜索文档和 Wiki 节点 | ✅ |

### 🎨 支持的样式功能

- **文本样式**：粗体、斜体、下划线、删除线、行内代码
- **文本颜色**：灰色、棕色、橙色、黄色、绿色、蓝色、紫色
- **对齐方式**：左对齐、居中、右对齐
- **标题级别**：支持1-9级标题
- **代码块**：支持多种编程语言语法高亮
- **列表**：有序列表（编号）、无序列表（项目符号）
- **图片**：支持本地图片和网络图片
- **文件附件**：支持任意格式文件，PDF 支持预览模式
- **公式**：在文本块中插入数学公式，支持LaTeX语法
- **Mermaid图表**：支持流程图、时序图、思维导图、类图、饼图等
- **表格**：支持创建多行列表格，单元格可包含文本、标题、列表、代码块等多种内容类型
- **飞书文档画板**：支持飞书文档的画板创建，提供更丰富和多样化的内容

---

## 🤖 配套 Claude Code Skill

本项目为 Claude Code 用户提供了配套的 `feishu-mcp-workflows` skill，涵盖所有 19 个工具的完整工作流与最佳实践。

### 安装方式

将 `.claude/skills/feishu-mcp-workflows.zip` 下载后，通过 Claude Code 安装：

```bash
# 下载 skill 压缩包
# 在 Claude Code 中安装：
/skills install feishu-mcp-workflows.zip
```

或者直接将 `.claude/skills/feishu-mcp-workflows/` 目录复制到你项目的 `.claude/skills/` 下。

### Skill 内容

该 skill 包含：
- 所有工具的参数说明与使用示例
- 推荐工作流（读取文档 → 按章节编辑 → 精准块操作）
- `lookup_block` / `lookup_block_index` 块索引查询工作流
- 图片、文件上传最佳实践
- Wiki 知识库操作指南
- 常见场景的完整操作链路

> 在使用飞书 MCP 工具前调用此 skill，可显著减少试错次数，提升操作准确率。

---

## 🔧 飞书配置教程

**⚠️ 重要提示：在开始使用之前，必须先完成飞书应用配置，否则无法正常使用本工具。**

关于如何创建飞书应用和获取应用凭证的说明可以在[官方教程](https://open.feishu.cn/document/home/develop-a-bot-in-5-minutes/create-an-app)找到。

**详细的飞书应用配置步骤**：有关注册飞书应用、配置权限、添加文档访问权限的详细指南，请参阅 [手把手教程 FEISHU_CONFIG.md](FEISHU_CONFIG.md)。

---

## 🏃‍♂️ 快速开始

### 方式一：NPM 直接使用（推荐）

```bash
npx feishu-docx-mcp --stdio
```

在 Claude Code、Cursor、Cline 等工具中，将以下配置加入 MCP 配置文件：

```json
{
  "mcpServers": {
    "feishu-docx-mcp": {
      "command": "npx",
      "args": ["-y", "feishu-docx-mcp", "--stdio"],
      "env": {
        "FEISHU_APP_ID": "cli_xxxxxxxxxx",
        "FEISHU_APP_SECRET": "xxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

如需启用图片 AI 分析功能，额外添加以下可选配置：

```json
{
  "env": {
    "FEISHU_APP_ID": "cli_xxxxxxxxxx",
    "FEISHU_APP_SECRET": "xxxxxxxxxxxxxxxx",
    "IMAGE_AI_PROVIDER": "anthropic",
    "IMAGE_AI_API_KEY": "sk-ant-xxxxxxxx",
    "IMAGE_AI_MODEL": "claude-haiku-4-5-20251001",
    "IMAGE_AI_MAX_IMAGES": "10"
  }
}
```

### 方式二：本地源码运行

1. **克隆仓库**
   ```bash
   git clone https://github.com/scribblerR/Feishu-MCP.git
   cd Feishu-MCP
   ```

2. **配置环境变量（复制 `.env.example` 为 `.env`）**

3. **编辑 `.env` 文件**
   ```env
   FEISHU_APP_ID=cli_xxxxx
   FEISHU_APP_SECRET=xxxxx
   FEISHU_AUTH_TYPE=tenant/user
   ```

4. **安装依赖并启动**
   ```bash
   pnpm install
   pnpm run dev
   ```

   或使用 Docker Compose：
   ```bash
   docker-compose up -d
   docker-compose logs -f
   ```

## ⚙️ 项目配置

### 环境变量配置

| 变量名 | 必需 | 描述 | 默认值 |
|--------|------|------|-------|
| `FEISHU_APP_ID` | ✅ | 飞书应用 ID | - |
| `FEISHU_APP_SECRET` | ✅ | 飞书应用密钥 | - |
| `FEISHU_AUTH_TYPE` | ❌ | 认证类型：`tenant`（应用级，默认）或 `user`（用户级，需 OAuth 授权） | `tenant` |
| `PORT` | ❌ | HTTP 模式服务器端口 | `3333` |
| `IMAGE_AI_PROVIDER` | ❌ | 图片 AI 分析服务商（目前支持 `anthropic`） | - |
| `IMAGE_AI_API_KEY` | ❌ | 图片 AI 服务 API Key | - |
| `IMAGE_AI_MODEL` | ❌ | 图片 AI 使用的模型 | - |
| `IMAGE_AI_MAX_IMAGES` | ❌ | 每次文档读取最多分析的图片数量 | `5` |

### HTTP 模式配置（多用户 SSE 服务）

如需以 HTTP 服务方式运行（支持多用户共享），在 MCP 配置中使用：

```json
{
  "mcpServers": {
    "feishu_local": {
      "url": "http://localhost:3333/sse?userKey=<随机字符串>"
    }
  }
}
```

**⚠️ 重要提示**：`userKey` 是用户唯一标识，请使用随机字符串，避免与其他用户冲突。

---

## 📝 使用贴士（重要）

1. ### **推荐指定文件夹**：
   新建文档时，建议主动提供飞书文件夹 token（可为具体文件夹或根文件夹），这样可以更高效地定位和管理文档。如果不确定具体的子文件夹，可以让LLM自动在你指定的文件夹下查找最合适的子目录来新建文档。

   > **如何获取文件夹 token？**
   > 打开飞书文件夹页面，复制链接（如 `https://.../drive/folder/xxxxxxxxxxxxxxxxxxxxxx`），token 就是链接最后的那一串字符（如 `xxxxxxxxxxxxxxxxxxxxxx`，请勿泄露真实 token）。

2. ### **Markdown 编辑优先**：
   编辑已有文档时，优先使用 `get_feishu_document_blocks`（outline 模式）查看大纲，再用 `replace_feishu_document_section` 按标题替换章节内容，比逐块操作效率高得多。

3. ### **图片上传路径说明**：
   本地运行 MCP 时，图片路径既支持本地绝对路径，也支持 http/https 网络图片；如在服务器环境，仅支持网络图片链接（由于cursor调用mcp时参数长度限制，暂不支持直接上传图片文件本体，请使用图片路径或链接方式上传）。

4. ### **公式使用说明**：
   在文本块中可以混合使用普通文本和公式元素。公式使用LaTeX语法，如：`1+2=3`、`\frac{a}{b}`、`\sqrt{x}`等。支持在同一文本块中包含多个公式和普通文本。

5. ### **使用飞书user认证**：
   user认证与tenant认证在增加权限时是有区分的，所以**在初次由tenant切换到user时需要注意配置的权限**；为了区分不同的用户需要在配置mcp server服务的url增加query参数：userKey，**该值是用户的唯一标识 所以最好在设置时越随机越好**

6. ### **强烈建议使用user认证**：
   tenant认证有诸多限制，比如文件访问权限、飞书openapi兼容(不支持搜索wiki文档)、文档创建编辑记录等方面都不如user认证。

---
## 🚨 故障排查

### 权限问题排查
先对照配置问题查看： [手把手教程 FEISHU_CONFIG.md](FEISHU_CONFIG.md)。

#### 问题确认
1. **检查应用权限**：确保应用已获得必要的文档访问权限
2. **验证文档授权**：确认目标文档已授权给应用或应用所在的群组
3. **检查可用范围**：确保应用发布版本的可用范围包含文档所有者

#### 权限验证与排查
1. 获取token：[自建应用获取 app_access_token](https://open.feishu.cn/api-explorer?apiName=app_access_token_internal&project=auth&resource=auth&version=v3)
2. 使用第1步获取的token，验证是否有权限访问该文档：[获取文档基本信息](https://open.feishu.cn/api-explorer?apiName=get&project=docx&resource=document&version=v1)


### 常见问题

- **找不到应用**：检查应用是否已发布且可用范围配置正确
- **权限不足**：参考[云文档常见问题](https://open.feishu.cn/document/ukTMukTMukTM/uczNzUjL3czM14yN3MTN)
- **知识库访问问题**：参考[知识库常见问题](https://open.feishu.cn/document/server-docs/docs/wiki-v2/wiki-qa)

---

## 📚 开发者 Wiki

详细的开发文档和技术指南，为学习者和贡献者提供全面的指导：

- **[Wiki 首页](https://github.com/cso1z/Feishu-MCP/wiki)** - 完整的文档索引和快速导航
- **[架构设计](https://github.com/cso1z/Feishu-MCP/wiki/架构设计)** - 整体架构和技术栈说明
- **[核心模块详解](https://github.com/cso1z/Feishu-MCP/wiki/核心模块详解)** - 各模块的实现细节和代码示例
- **[认证与授权](https://github.com/cso1z/Feishu-MCP/wiki/认证与授权机制)** - Token 管理和多用户支持机制
- **[开发者指南](https://github.com/cso1z/Feishu-MCP/wiki/开发者指南)** - 环境搭建、开发流程、调试技巧
- **[API 参考](https://github.com/cso1z/Feishu-MCP/wiki/API-参考文档)** - 所有工具函数的详细文档
- **[最佳实践](https://github.com/cso1z/Feishu-MCP/wiki/最佳实践)** - 代码规范、性能优化、安全实践
- **[MCP 协议实现](https://github.com/cso1z/Feishu-MCP/wiki/MCP-协议实现)** - MCP 协议详解和传输层实现

---

## 💖 支持项目

如果这个项目帮助到了你，请考虑：

- ⭐ 给项目一个 Star
- 🐛 报告 Bug 和问题
- 💡 提出新功能建议
- 📖 改进文档
- 🔀 提交 Pull Request

你的支持是我们前进的动力！

---

> 本项目 fork 自 [cso1z/Feishu-MCP](https://github.com/cso1z/Feishu-MCP)，遵循原项目 MIT 协议。