<div align="center">

🔗 Feishu MCP Server

让 AI 助手直接读写飞书文档

English | 中文

</div>

---

✨ 简介

Feishu MCP Server 是一个基于 Model Context Protocol (MCP) 的飞书文档集成服务。它让 AI 助手（如 GitHub Copilot、Claude、Cursor 等）能够直接操作飞书文档，实现文档自动化。

🎯 应用场景

• 📝 技术文档自动生成 - AI 自动撰写设计文档、API 文档
• 📊 数据报表输出 - 将数据分析结果直接写入飞书
• 📋 会议纪要整理 - 自动生成结构化的会议记录
• 🔄 知识库维护 - 批量更新和管理知识库内容

---

🚀 功能特性

📄 文档操作

功能	工具	说明
读取文档	feishu_read_document	支持 Markdown/JSON 格式输出
创建文档	feishu_create_document	支持完整 Markdown 语法
追加内容	feishu_append_content	智能识别 Markdown 表格
更新内容	feishu_update_content	替换文档全部内容
文档信息	feishu_get_document_info	获取标题、ID、版本等

📊 富文本元素

功能	工具	说明
插入表格	feishu_insert_table	自适应列宽，支持 Markdown 表格语法
插入图表	feishu_insert_diagram	Mermaid 流程图、时序图、架构图
插入引用块	feishu_insert_callout	高亮提示信息
上传图片	feishu_upload_image	上传本地图片
插入图片	feishu_insert_image	将图片插入文档

📈 电子表格 & 多维表格

功能	工具	说明
创建电子表格	feishu_create_spreadsheet	创建新的 Sheet
写入数据	feishu_write_spreadsheet	批量写入单元格数据
读取数据	feishu_read_spreadsheet	读取指定范围数据
创建多维表格	feishu_create_bitable	创建 Bitable
添加记录	feishu_add_bitable_records	批量添加记录
读取记录	feishu_read_bitable	读取表格数据

🔧 块操作

功能	工具	说明
列出块	feishu_list_blocks	查看文档结构
删除块	feishu_delete_block	删除指定块

---

📦 快速开始

1. 安装

# 克隆项目
git clone https://github.com/redleaves/feishu-mcp-server.git
cd feishu-mcp-server

# 安装依赖
npm install

# 编译
npm run build

2. 配置飞书应用

1. 访问 飞书开放平台 创建应用
2. 获取 App ID 和 App Secret
3. 添加以下权限并发布应用：

权限标识	权限名称	用途
docx:document	查看、评论和编辑新版文档	文档读写
docx:document:readonly	查看新版文档	文档读取
wiki:wiki:readonly	查看知识库	知识库访问
drive:drive	查看、评论和编辑云空间中的文件	云空间操作
bitable:bitable	查看、评论和编辑多维表格	多维表格操作

3. 配置 MCP 客户端

<details> <summary><b>🐙 GitHub Copilot CLI</b></summary>

编辑 ~/.copilot/mcp-config.json：

{
  "mcpServers": {
    "feishu": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/feishu-mcp-server/dist/index.js"],
      "env": {
        "FEISHU_APP_ID": "cli_xxxxxxxx",
        "FEISHU_APP_SECRET": "your_app_secret"
      }
    }
  }
}

</details>

<details> <summary><b>🤖 Claude Desktop</b></summary>

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "feishu": {
      "command": "node",
      "args": ["/path/to/feishu-mcp-server/dist/index.js"],
      "env": {
        "FEISHU_APP_ID": "cli_xxxxxxxx",
        "FEISHU_APP_SECRET": "your_app_secret"
      }
    }
  }
}

</details>

<details> <summary><b>✨ Cursor</b></summary>

在 Cursor 设置中添加 MCP Server：

{
  "mcp.servers": {
    "feishu": {
      "command": "node",
      "args": ["/path/to/feishu-mcp-server/dist/index.js"],
      "env": {
        "FEISHU_APP_ID": "cli_xxxxxxxx",
        "FEISHU_APP_SECRET": "your_app_secret"
      }
    }
  }
}

</details>

---

💡 使用示例

创建技术设计文档

创建一个飞书文档，标题是"系统架构设计"，包含：
1. 项目背景
2. 技术方案（插入架构图）
3. 实施计划表格

读取并总结文档

读取这个飞书文档 https://xxx.feishu.cn/wiki/ABC123，帮我总结要点

插入数据表格

在文档中插入一个表格，展示各模块的开发进度

生成架构图

在文档中插入一个 Mermaid 流程图，展示用户登录流程

---

📐 技术架构

flowchart TB
    subgraph Clients["AI 客户端"]
        Copilot["GitHub Copilot"]
        Claude["Claude Desktop"]
        Cursor["Cursor"]
    end
    
    subgraph MCP["Feishu MCP Server"]
        Tools["18 个工具"]
        Auth["Token 管理"]
        API["API 封装"]
    end
    
    subgraph Feishu["飞书开放平台"]
        Doc["文档 API"]
        Drive["云空间 API"]
        Bitable["多维表格 API"]
    end
    
    Clients --> MCP
    MCP --> Feishu

---

⚠️ 已知限制

限制项	说明
API 频率	每秒最多 3 次请求
表格行数	单次创建最多 9 行（超出自动截断）
文件上传	最大 20MB
Token 有效期	2 小时（自动刷新）

---

🛠️ 开发指南

# 开发模式（热重载）
npm run dev

# 编译
npm run build

# 运行测试
npm test

# 代码检查
npm run lint

项目结构

feishu-mcp-server/
├── src/
│   ├── index.ts          # 入口文件
│   ├── constants.ts      # 常量定义
│   ├── types.ts          # 类型定义
│   ├── services/         # 服务层
│   │   ├── api.ts        # API 封装
│   │   └── auth.ts       # 认证服务
│   └── tools/            # MCP 工具
│       ├── document.ts   # 文档操作
│       ├── table.ts      # 表格操作
│       ├── block.ts      # 块操作
│       ├── media.ts      # 媒体操作
│       ├── spreadsheet.ts# 电子表格
│       └── bitable.ts    # 多维表格
├── dist/                 # 编译输出
└── docs/                 # 文档

---

🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

---

📄 许可证

本项目采用 MIT 许可证。

---

🔗 相关链接

• 飞书开放平台
• MCP 协议规范
• 飞书文档 API

---

<div align="center">

如果这个项目对你有帮助，请给个 ⭐ Star！

Made with ❤️ by [Your Name]

</div>