飞书 OAuth 与 MCP 协议的实战应用指南：基于 Cloudflare Workers 的远程连接解决方案

借助飞书 OAuth 与 MCP 协议，你可以构建一个可扩展、安全、零配置体验的远程交互服务器。本指南将详尽介绍项目背景、部署流程、技术原理与实际接入方式，帮助你快速落地这一技术栈。

一、项目概述

本文围绕一个基于 模型上下文协议（MCP） 的服务器实现展开。该服务器集成了 飞书 OAuth 认证机制，允许用户通过飞书账户安全登录，并连接到部署在 Cloudflare Workers 的远程 MCP 服务端。

该项目基于 Cloudflare 官方远程 MCP GitHub OAuth 示例 改造，将 GitHub 登录改为更适合国内用户的飞书登录方式。

二、核心优势与设计目标

与飞书官方 MCP Server 的差异

项目特色一览

• 飞书 OAuth 登录集成：确保企业级认证安全
• 零配置自动体验：自动管理 user_access_token 生命周期
• 优化的工具集：特别为复杂文档操作设计
• 全球部署支持：依托 Cloudflare Workers 的边缘计算平台
• 多客户端支持：兼容 ChatWise、Cursor、Inspector 等主流 MCP 客户端

三、快速开始

准备条件

项目安装

# 克隆项目
git clone <repository-url>
cd my-mcp-server

# 安装依赖
npm install

四、部署指南

1. 生产环境部署步骤

Step 1：创建飞书应用

1. 访问 飞书开放平台

2. 登录后进入“开发者后台”，创建新应用

3. 设置应用权限，包括：

   • 获取用户 ID（auth:user.id:read）
   • 获取任务信息（task:task:read）
   • 离线访问授权（offline_access）
   • 读取用户资料（user_profile）

4. 获取 App ID 和 App Secret

Step 2：配置 Cloudflare Worker 环境

wrangler secret put FEISHU_APP_ID
wrangler secret put FEISHU_APP_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY  # openssl rand -hex 32 生成

创建 KV 存储空间：

wrangler kv:namespace create "OAUTH_KV"

Step 3：更新配置文件

将创建出的 KV 命名空间 ID，填写进 wrangler.toml 中。

Step 4：部署 MCP 服务器

wrangler deploy

部署完成后记录 Cloudflare 分配的域名（subdomain）。

Step 5：配置飞书重定向 URL

回到飞书应用后台：

• 安全设置 → 重定向 URL
• 添加：https://feishu-mcp-server.<your-subdomain>.workers.dev/callback

2. 本地开发环境配置

步骤一：本地重定向设置

在飞书安全设置中添加：http://localhost:8788/callback

步骤二：创建 .dev.vars 文件

FEISHU_APP_ID=your_dev_app_id
FEISHU_APP_SECRET=your_dev_app_secret
COOKIE_ENCRYPTION_KEY=random_string

步骤三：启动开发服务器

wrangler dev

默认运行地址：http://localhost:8788

五、客户端接入方式

1. 使用 MCP Inspector

npx @modelcontextprotocol/inspector@latest

连接地址：

• 生产环境：https://feishu-mcp-server.<your-subdomain>.workers.dev/sse
• 本地开发：http://localhost:8788/sse

2. 使用 Cursor 客户端

快捷接入方式：

或者手动配置：

{
  "mcpServers": {
    "feishu": {
      "url": "http://localhost:8788/sse"
    }
  }
}

3. 使用 ChatWise

1. 打开 ChatWise 设置
2. 添加工具：命令行为 npx -y mcp-remote ${URL}
3. 登录成功后飞书功能即可使用

六、访问控制机制

• 身份认证机制：通过飞书 OAuth 实现
• 权限策略：所有飞书授权用户默认可访问 MCP 工具

七、功能开发路线图

已完成部分

• 文档块结构解析
• 文档块创建、更新、删除
• 表格操作
• 素材上传（图像、视频）
• Markdown 导入支持

计划开发

八、系统架构与技术原理

核心组件

OAuth Provider 模块

• 实现 OAuth 2.1 全流程
• 管理用户授权与 access_token
• 连接飞书 OAuth 服务

Durable MCP 模块

• 使用 Cloudflare Durable Objects 实现持久连接
• 持有用户上下文信息，管理登录状态
• 接入点：this.props

MCP Remote 模块

• 定义远程客户端通信协议
• 使用 SSE 维护长连接
• 支持结构化工具定义与序列化请求处理

九、开发者实用说明

本项目一方面充当 OAuth 服务端，另一方面又是飞书 OAuth 的 客户端，具备双重角色。

安全设计

• 所有工具调用均绑定用户 access_token
• 遵守飞书权限范围限制
• 错误捕获与日志记录内建支持

📸 推荐图片资源（版权自由）

• Unsplash：Cloudflare
• Pexels：OAuth login

结语

借助 MCP 协议与飞书 OAuth 的结合，你可以快速构建支持安全认证、高可用部署、工具拓展灵活的 AI 应用服务端。不论是用于内部团队效率工具，还是作为 AI 服务中台解决方案，本项目都提供了极具价值的工程参考。