飞书MCP服务器
飞书MCP服务器是一个基于Model Context Protocol的服务，提供飞书API集成，使AI模型能够轻松与飞书服务交互。
目录
功能特点
- 文档服务：读取飞书文档内容和元数据
- 机器人服务：发送文本消息和交互卡片到飞书聊天
- 聊天服务：管理群组和聊天会话
- 多模式支持：
- STDIO模式：通过标准输入/输出通信，适用于CLI环境和集成到其他应用
- HTTP模式：提供REST API和SSE连接，适用于Web服务和分布式部署
- 完善的错误处理：统一的错误处理机制，提供详细的错误信息
- 类型安全：基于TypeScript，提供完整的类型定义
- 模块化架构：易于扩展新功能和集成其他飞书API
项目架构
代码结构
/src
/client # API客户端实现（底层API请求封装）
/documents # 文档相关API客户端
/bots # 机器人API客户端
/chats # 聊天相关API客户端
/services # 服务层实现（业务逻辑和错误处理）
/documents # 文档相关服务
/bots # 机器人相关服务
/chats # 聊天相关服务
/server # MCP服务器实现
/tools # MCP工具注册和实现
/typings # 类型定义
/utils # 通用工具函数
/http # HTTP服务器实现
/logger # 日志服务
/consts # 常量定义
config.ts # 配置管理
index.ts # 入口点
设计原则
项目采用分层架构设计，确保关注点分离和职责明确：
1. 分层职责
-
客户端层（Client）
- 封装HTTP请求的细节
- 处理底层API参数和响应格式
- 管理认证和令牌刷新
- 不包含业务逻辑
-
服务层（Service）
- 使用客户端执行API操作
- 实现业务逻辑
- 处理和转换错误
- 提供友好的接口给上层使用
-
工具层（Tools）
- 实现MCP协议定义的工具
- 处理参数验证和格式转换
- 调用服务层完成实际操作
- 格式化返回结果
2. 依赖方向
- 服务层依赖客户端层
- 工具层依赖服务层
- 严格避免循环依赖
3. 错误处理策略
- 使用
FeiShuApiError统一处理API错误 - 客户端层返回原始错误
- 服务层捕获并转换为业务相关错误
- 工具层处理所有异常并返回用户友好消息
工作流程
- MCP服务器接收请求（STDIO或HTTP）
- 工具层验证参数并调用相应服务
- 服务层实现业务逻辑并调用客户端
- 客户端执行实际API请求并返回结果
- 结果经由服务层处理后返回给工具层
- 工具层格式化结果并返回给MCP服务器
快速开始
前提条件
- Node.js 23.0或更高版本
- pnpm包管理器
- 有效的飞书开发者账号和已创建的自建应用
安装步骤
- 克隆仓库
git clone https://github.com/yourusername/feishu-mcp-server.git
cd feishu-mcp-server
- 安装依赖
pnpm install
- 创建
.env文件
# 飞书应用凭证（必填）
FEISHU_APP_ID=your_app_id
FEISHU_APP_SECRET=your_app_secret
# 服务器配置（可选）
PORT=3344
LOG_LEVEL=info
运行服务
开发模式
# 开发模式（自动重启）
pnpm dev
# 或使用普通启动
pnpm start
生产模式
# 构建项目
pnpm build
# 运行编译后的代码
node dist/index.js
STDIO模式
# 方法1：使用环境变量
NODE_ENV=cli node dist/index.js
# 方法2：使用命令行参数
node dist/index.js --stdio
配置说明
| 选项 | 环境变量 | 命令行参数 | 默认值 | 描述 |
|---|---|---|---|---|
| 飞书应用ID | FEISHU_APP_ID | --feishu-app-id | - | 飞书自建应用的App ID |
| 飞书应用密钥 | FEISHU_APP_SECRET | --feishu-app-secret | - | 飞书自建应用的App Secret |
| 服务器端口 | PORT | --port | 3344 | HTTP服务器端口号 |
| 日志级别 | LOG_LEVEL | --log-level | info | 日志级别(debug/info/warn/error) |
| 令牌缓存时间 | TOKEN_CACHE_DURATION | - | 7100 | 访问令牌缓存时间(秒) |
API文档
文档操作
get_feishu_doc_raw
获取飞书文档的原始内容。
参数：
docId- 文档ID，通常在URL中找到 (例如：feishu.cn/docx/)
返回：
- 文档的文本内容
get_feishu_doc_info
获取飞书文档的元数据信息。
参数：
docId- 文档ID
返回：
- 文档的元数据（JSON格式）
机器人操作
send_feishu_text_message
发送文本消息到飞书聊天。
参数：
chatId- 聊天IDtext- 要发送的文本内容
返回：
- 发送状态和消息ID
send_feishu_card
发送交互卡片到飞书聊天。
参数：
chatId- 聊天IDcardContent- 卡片内容（JSON字符串）
返回：
- 发送状态和消息ID
聊天操作
get_feishu_chat_info
获取飞书聊天的基本信息。
参数：
chatId- 聊天ID
返回：
- 聊天的基本信息（JSON格式）
多维表格操作
get_feishu_sheet_meta
获取飞书多维表格的元数据信息。
参数：
appToken- 多维表格ID，通常在URL中找到 (例如：feishu.cn/base/或 feishu.cn/app/ )
返回：
- 多维表格的元数据（JSON格式），包含表格ID、名称、修订版本、创建者、创建时间、权限等信息
get_feishu_sheet_tables
获取飞书多维表格中的数据表列表。
参数：
appToken- 多维表格ID，通常在URL中找到 (例如：feishu.cn/base/或 feishu.cn/app/ ) pageSize- 每页返回的数据表数量，可选，默认为20，最大为100pageToken- 分页标记，可选，用于获取下一页数据
返回：
- 数据表列表（JSON格式），包含表ID、名称、字段信息等
get_feishu_sheet_views
获取飞书多维表格中数据表的视图列表。
参数：
appToken- 多维表格ID，通常在URL中找到 (例如：feishu.cn/base/或 feishu.cn/app/ ) tableId- 数据表IDpageSize- 每页返回的视图数量，可选，默认为20，最大为100pageToken- 分页标记，可选，用于获取下一页数据
返回：
- 视图列表（JSON格式），包含视图ID、名称、类型和属性等信息
get_feishu_sheet_view
获取飞书多维表格中数据表特定视图的详细信息。
参数：
appToken- 多维表格ID，通常在URL中找到 (例如：feishu.cn/base/或 feishu.cn/app/ ) tableId- 数据表IDviewId- 视图ID，要获取详细信息的视图
返回：
- 视图详情（JSON格式），包含视图ID、名称、类型和属性等信息
get_feishu_sheet_records
获取飞书多维表格中的数据表记录。
参数：
appToken- 多维表格ID，通常在URL中找到 (例如：feishu.cn/base/或 feishu.cn/app/ ) tableId- 数据表IDviewId- 视图ID，可选，不指定时使用默认视图fieldIds- 字段ID列表，可选，指定返回哪些字段filter- 过滤条件，可选，使用FQL格式sort- 排序条件，可选，使用JSON格式pageSize- 每页返回的记录数量，可选，默认为20，最大为100pageToken- 分页标记，可选，用于获取下一页数据
返回：
- 记录列表（JSON格式），包含记录ID和字段值
get_feishu_sheet_record
获取飞书多维表格中的单条记录。
参数：
appToken- 多维表格ID，通常在URL中找到 (例如：feishu.cn/base/或 feishu.cn/app/ ) tableId- 数据表IDrecordId- 记录IDfieldIds- 字段ID列表，可选，指定返回哪些字段
返回：
- 单条记录（JSON格式），包含记录ID和字段值
开发指南
代码规范
项目使用严格的TypeScript规范和ESLint配置：
- 使用TypeScript接口和类型定义
- 避免使用
any类型 - 使用
Record<string, unknown>替代object类型 - 所有代码文件、注释和错误消息使用英文
运行代码检查：
# 运行代码检查
pnpm lint
# 运行代码检查并修复
pnpm lint:fix
# 运行代码格式化
pnpm format
错误处理
所有与飞书API相关的错误应使用 FeiShuApiError 类处理：
try {
// API操作
} catch (error) {
if (error instanceof FeiShuApiError) {
// 处理特定的API错误
logger.error(`FeiShu API Error (${error.code}): ${error.message}`);
} else {
// 处理通用错误
logger.error('Unexpected error:', error);
}
// 转换为用户友好消息
throw new FeiShuApiError('操作失败', { cause: error });
}
提交规范
提交消息必须遵循以下格式：
<type>(<scope>): <subject>
例如：
feat(bot): 添加发送卡片功能fix(documents): 修复文档内容获取错误
支持的类型：
feat: 新功能fix: 修复Bugdocs: 文档变更style: 代码格式调整refactor: 代码重构perf: 性能优化test: 测试相关chore: 构建过程或辅助工具的变动
扩展指南
添加新功能的步骤：
-
创建客户端类
- 在
src/client/<feature>/目录下创建 - 继承
ApiClient基类 - 实现API请求方法
// src/client/feature/feature-client.ts export class FeatureClient extends ApiClient { async getFeatureData(id: string): Promise<FeatureData> { return this.request<FeatureResponse>('/feature/get', { id }); } } - 在
-
创建服务类
- 在
src/services/<feature>/目录下创建 - 使用相应的客户端类
- 实现业务逻辑和错误处理
// src/services/feature/feature-service.ts export class FeatureService { private client: FeatureClient; constructor(config: ApiClientConfig) { this.client = new FeatureClient(config); } async getFeature(id: string): Promise<Feature> { try { const data = await this.client.getFeatureData(id); return this.transformData(data); } catch (error) { handleError(error); } } } - 在
-
注册服务
- 在
src/services/index.ts中导出新服务 - 将服务添加到
FeiShuServices类
- 在
-
创建MCP工具
- 在
src/server/tools/feature-tools.ts中创建 - 使用Zod进行参数验证
- 调用服务层方法
// src/server/tools/feature-tools.ts export function registerFeatureTools(params: ToolRegistryParams): void { const { server, services, logger } = params; server.tool( 'get_feishu_feature', 'Get feature from FeiShu', { id: z.string().describe('Feature ID'), }, async ({ id }) => { try { const feature = await services.feature.getFeature(id); return { content: [{ type: 'text', text: JSON.stringify(feature) }] }; } catch (error) { return handleToolError(error, logger); } } ); } - 在
-
注册工具
- 在
src/server/tools/index.ts中引入并注册新工具
- 在
常见问题
认证失败
问题：API请求返回认证错误
解决方案：
- 检查应用ID和密钥是否正确
- 确认应用具有所需的权限范围
- 检查服务器时间是否正确同步
令牌刷新问题
问题：令牌刷新失败
解决方案：
- 设置更短的令牌缓存时间
- 检查网络连接稳定性
- 查看飞书开发者平台的应用状态
许可证
MIT
贡献指南
欢迎贡献！请遵循以下步骤：
- Fork仓库
- 创建功能分支（
git checkout -b feature/amazing-feature） - 提交更改（
git commit -m 'feat: add some amazing feature'） - 推送到分支（
git push origin feature/amazing-feature） - 开启Pull Request
提交PR前请确保：
- 代码通过所有测试
- 更新了相关文档
- 遵循项目的代码风格和命名约定
- 添加必要的单元测试