Skip to content
Back to search

open-feishu-mcp-server

这是一个支持远程连接的模型上下文协议 (MCP) 服务器,内置了飞书 OAuth 认证。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ztxtxwd--open-feishu-mcp-server/badge.svg)](/listings/ztxtxwd--open-feishu-mcp-server)

HTML

<a href="/listings/ztxtxwd--open-feishu-mcp-server"><img src="/api/listings/ztxtxwd--open-feishu-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 克隆仓库
git clone <repository-url>
cd open-feishu-mcp-server

# 安装依赖
npm install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 284 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

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

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.