飞书 MCP Server

1[![MCP Badge](https://lobehub.com/badge/mcp/ztxtxwd-open-feishu-mcp-server)](https://lobehub.com/mcp/ztxtxwd-open-feishu-mcp-server)
2 
3[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/ztxtxwd/open-feishu-mcp-server)](https://archestra.ai/mcp-catalog/ztxtxwd__open-feishu-mcp-server)
4# 飞书 MCP Server
5 
6[English Documentation](README.en.md)
7 
8这是一个支持远程连接的[模型上下文协议 (MCP)](https://modelcontextprotocol.io/introduction) 服务器，内置了飞书 OAuth 认证。
9 
10本项目修改自 [cloudflare/ai/demos/remote-mcp-github-oauth](https://github.com/cloudflare/ai/tree/main/demos/remote-mcp-github-oauth)，将 GitHub OAuth 替换为飞书 OAuth。
11 
12您可以将其部署到自己的 Cloudflare 账户，并在创建自己的飞书 OAuth 客户端应用后，拥有一个功能完整的远程 MCP 服务器。用户可以通过飞书账号登录连接到您的 MCP 服务器。
13 
14## 📋 目录
15 
16- [与飞书官方 MCP Server 的区别](#-与飞书官方-mcp-server-的区别)
17- [特性](#-特性)
18- [快速开始](#-快速开始)
19- [部署方式](#-部署方式)
20  - [生产环境部署](#生产环境部署)
21  - [本地开发环境](#本地开发环境)
22- [客户端集成](#-客户端集成)
23  - [使用 Inspector 测试](#使用-inspector-测试)
24  - [使用 Cursor](#使用-cursor)
25  - [使用 ChatWise](#使用-chatwise)
26- [访问控制](#-访问控制)
27- [工具开发路线图](#-工具开发路线图)
28- [技术原理](#-技术原理)
29- [开发指南](#-开发指南)
30 
31 
32## 🆚 与飞书官方 MCP Server 的区别
33 
34虽然飞书官方也推出了 MCP Server，但本项目在以下几个方面具有显著优势：
35 
36### 🎯 零配置体验
37- **本项目**：用户无需手动配置任何参数，全程使用 `user_access_token`，过期自动刷新
38- **官方项目**：需要用户手动配置多个参数，配置复杂
39 
40### 🚀 极致的可用性优化
41- **本项目**：深度优化工具尺寸和结构，特别是文档创建块工具、创建嵌套块工具等复杂功能，确保在 Cursor 等客户端中正常使用
42- **官方项目**：简单的 API 到 MCP 工具转换，部分工具过于庞大，在实际使用中存在可用性问题
43 
44### 🌐 前沿基础设施
45- 支持部署在 Cloudflare Workers，享受业界最前沿的边缘计算基础设施
46## ✨ 特性
47 
48- 🎯 **零配置体验**：用户无需手动配置参数，自动管理 `user_access_token` 和刷新
49- 🔐 **飞书 OAuth 认证**：安全的用户身份验证
50- 🌐 **远程 MCP 服务器**：支持多客户端连接
51- 🚀 **Cloudflare Workers**：高性能、全球分布式部署，享受业界最前沿的边缘计算基础设施
52- 🛠️ **深度优化的工具集**：特别优化文档创建、嵌套块等复杂工具，确保在各种客户端中正常使用
53- 🔧 **本地开发支持**：便于开发和测试的本地环境
54- ⚡ **极致可用性**：相比官方 MCP Server，大幅提升实际使用体验和稳定性
55 
56## 🚀 快速开始
57 
58### 前置要求
59 
60- Node.js 18+ 和 npm
61- Cloudflare 账户
62- 飞书开放平台账户
63 
64### 安装
65 
66```bash
67# 克隆仓库
68git clone <repository-url>
69cd open-feishu-mcp-server
70 
71# 安装依赖
72npm install
73```
74 
75## 🚀 部署方式
76 
77### 生产环境部署
78 
79#### 步骤 1: 创建飞书应用
80 
811. 访问[飞书开放平台](https://open.feishu.cn/)并登录
822. 点击"开发者后台"并创建一个新应用
833. 在应用设置中配置权限：
84   - 进入"权限与功能"并添加以下权限：
85     - "获取用户 ID" (auth:user.id:read)
86     - "获取用户任务信息" (task:task:read)
87     - "获取用户授权凭证" (offline_access)
88     - "获取用户基本信息" (user_profile)
89     
90        ...
914. 记下您的**应用 ID** 和**应用密钥**
92 
93#### 步骤 2: 配置 Cloudflare 环境
94 
95```bash
96# 设置必要的密钥
97wrangler secret put FEISHU_APP_ID
98wrangler secret put FEISHU_APP_SECRET
99wrangler secret put COOKIE_ENCRYPTION_KEY  # 使用 openssl rand -hex 32 生成
100 
101# 创建 KV 命名空间
102wrangler kv namespace create "OAUTH_KV"
103```
104 
105#### 步骤 3: 更新配置文件
106 
107使用步骤 2 中获得的 KV ID 更新 `wrangler.toml` 文件中的 KV 命名空间配置。
108 
109#### 步骤 4: 部署服务器
110 
111```bash
112npm run deploy
113```
114 
115部署完成后，记下您的实际 subdomain（会在部署日志中显示）。
116 
117#### 步骤 5: 配置重定向 URL
118 
119回到飞书应用设置：
1201. 进入"安全设置"
1212. 添加重定向 URL：`https://feishu-mcp-server.<your-actual-subdomain>.workers.dev/callback`
122 
123### 本地开发环境
124 
125#### 配置本地环境
126 
1271. **配置飞书应用**：
128   - 在飞书应用的"安全设置"中添加：`http://localhost:8788/callback`
129   - 确保拥有所需的权限（同生产环境）
130 
1312. **创建环境变量文件**：
132   在项目根目录创建 `.dev.vars` 文件：
133   ```
134   FEISHU_APP_ID=your_development_feishu_app_id
135   FEISHU_APP_SECRET=your_development_feishu_app_secret
136   COOKIE_ENCRYPTION_KEY=any_random_string_here
137   ```
138 
139#### 启动本地服务器
140 
141```bash
142npm run dev
143```
144 
145服务器将在 `http://localhost:8788` 运行。
146 
147## 🔌 客户端集成
148 
149### 使用 Inspector 测试
150 
151使用官方的 MCP Inspector 测试您的服务器：
152 
153```bash
154npx @modelcontextprotocol/inspector@latest
155```
156 
157**连接地址**：
158- 生产环境：`https://feishu-mcp-server.<your-subdomain>.workers.dev/sse`
159- 本地环境：`http://localhost:8788/sse`
160 
161### 使用 Cursor
162 
163通过一键安装按钮快速配置：
164 
165[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=feishu&config=eyJ1cmwiOiJodHRwOi8vbG9jYWxob3N0Ojg3ODgvc3NlIn0%3D)
166 
167或手动配置：
168 
169```json
170{
171  "mcpServers": {
172    "feishu": {
173      "url": "http://localhost:8788/sse"
174    }
175  }
176}
177```
178 
179### 使用 ChatWise
180 
1811. **配置步骤**：
182   - 打开 ChatWise 设置界面
183   - 导航到工具选项
184   - 新增命令行输入输出（stdio）
185   - 命令：`npx -y mcp-remote ${URL}`
186 
1872. **连接地址**：
188   - 本地：`http://localhost:8788/sse`
189   - 生产：`https://feishu-mcp-server.<your-subdomain>.workers.dev/sse`
190 
1913. **首次使用**：
192   - 保存配置后会自动打开飞书 OAuth 登录页面
193   - 完成授权即可使用飞书相关功能
194 
195## 🔐 访问控制
196 
197- **身份验证**：使用飞书 OAuth 进行用户身份验证
198- **权限范围**：所有经过身份验证的飞书用户都可以访问所有工具
199 
200## 📋 工具开发路线图
201 
202### 🚧 当前开发中 (飞书文档)
203- **🔧开发辅助工具**
204  - ✅ 开发文档内容搜索与召回
205- **📄 文档基础操作**
206  - ✅ 文档块树结构获取
207  - ✅ 获取块类型创建参数 schema
208  - ✅ 创建文档块（支持各种块类型）
209  - ✅ 更新文档块内容
210  - ✅ 批量删除文档块
211- **🔧 文档高级功能**
212  - ✅ 表格创建与操作
213  - ✅ 图片、视频、文件上传与插入
214  - ✅ Markdown 导入功能
215  - ✅ 素材上传与管理
216  - ✅ 文档搜索
217 
218### 🎯 未来计划
219- **📊 电子表格（Sheets）**
220  - 📋 工作表基础操作（创建、删除、重命名）
221  - 📋 单元格数据读写
222  - 📋 公式计算与应用
223  - 📋 图表创建与编辑
224  - 📋 数据筛选与排序
225  - 📋 协作与权限管理
226 
227- **🗃️ 多维表格（Base/Bitable）**
228  - 📋 数据表基础操作
229  - 📋 记录增删改查
230  - 📋 字段类型管理
231  - 📋 视图创建与配置
232  - 📋 自动化规则设置
233  - 📋 数据导入导出
234 
235  ...
236 
237**图例**：✅ 已完成 | 🔄 开发中 | 📋 计划中
238 
239## 🛠️ 技术原理
240 
241### 架构组件
242 
243#### OAuth Provider
244完整的 OAuth 2.1 服务器实现，处理：
245- MCP 客户端身份验证
246- 飞书 OAuth 服务连接管理
247- KV 存储中的安全令牌管理
248 
249#### Durable MCP
250基于 Cloudflare Durable Objects 的 MCP 扩展：
251- 持久状态管理
252- 身份验证上下文存储
253- 通过 `this.props` 访问用户信息
254- 基于用户身份的条件工具可用性
255 
256#### MCP Remote
257支持远程 MCP 客户端连接：
258- 定义客户端-服务器通信协议
259- 提供结构化工具定义方式
260- 处理请求/响应序列化
261- 维护 SSE 连接
262 
263## 👨‍💻 开发指南
264 
265### MCP 服务器（由 [Cloudflare Workers](https://developers.cloudflare.com/workers/) 提供支持）
266 
267本项目实现了双重 OAuth 角色：
268* 对 MCP 客户端充当 OAuth **服务器**
269* 对飞书 OAuth 服务充当 OAuth **客户端**
270 
271### 工具开发
272 
273当前工具使用用户访问令牌进行身份验证，确保：
274- 安全访问飞书 API
275- 基于用户权限的功能访问
276- 完整的错误处理和日志记录
277 
278---
279 
280**📝 注意**：确保在部署前正确配置所有环境变量和飞书应用设置。如遇问题，请检查飞书应用权限配置和重定向 URL 设置。
281 
282## Star History
283 
284[![Star History Chart](https://api.star-history.com/svg?repos=ztxtxwd/open-feishu-mcp-server&type=Date)](https://star-history.com/#ztxtxwd/open-feishu-mcp-server&Date)
285