MCP飞书服务

你是否曾经希望AI能够直接读取飞书文档、发送消息到飞书群聊，甚至操作多维表格？今天要介绍的开源项目MCP飞书服务，正是为了实现这个目标而设计的。它基于模型上下文协议，提供飞书API集成，使AI模型能够轻松与飞书服务交互。

项目基本信息

一、项目介绍

MCP飞书服务是一个让AI能够与飞书平台交互的MCP服务器。它提供了飞书API的完整集成，支持文档服务、机器人服务、聊天服务以及多维表格操作。

这个服务器提供了以下功能类别：

• 文档服务：读取飞书文档内容和元数据
• 机器人服务：发送文本消息和交互卡片到飞书聊天
• 聊天服务：管理群组和聊天会话
• 多维表格服务：获取表格元数据、数据表列表、视图列表、记录查询等

服务器支持两种运行模式：

• STDIO模式：通过标准输入/输出通信，适用于CLI环境和集成到其他应用
• HTTP模式：提供REST API和SSE连接，适用于Web服务和分布式部署

二、核心优势

功能全面

覆盖飞书核心功能：

• 文档读取（内容和元数据）
• 消息发送（文本和卡片）
• 聊天管理
• 多维表格操作

分层架构设计

采用清晰的分层架构：

• 客户端层：封装HTTP请求细节
• 服务层：实现业务逻辑
• 工具层：实现MCP协议工具

多模式支持

支持STDIO和HTTP两种运行模式，适应不同部署场景。

类型安全

基于TypeScript，提供完整的类型定义，开发体验良好。

模块化架构

易于扩展新功能和集成其他飞书API。

三、适用场景

AI辅助办公自动化

让AI读取飞书文档内容、发送消息、操作表格，实现办公自动化。

智能客服机器人

AI可以接收用户消息，调用飞书API发送回复。

文档处理

AI可以读取飞书文档内容，进行分析、总结或翻译。

数据查询

AI可以查询多维表格中的记录，回答用户问题。

四、安装教程

系统要求

安装步骤

第一步：创建飞书自建应用

1. 登录飞书开发者后台
2. 创建企业自建应用
3. 记录App ID和App Secret
4. 配置应用权限（文档、消息、多维表格等）
5. 发布应用

第二步：克隆项目并安装依赖

git clone https://github.com/sdd330/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 build

# 生产模式启动
node dist/index.js

# 开发模式（自动重启）
pnpm dev

第五步：配置MCP客户端

对于Claude Desktop：

找到配置文件，添加：

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

HTTP模式：

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

五、使用示例

配置完成后，你就可以在MCP客户端中使用自然语言来调用飞书功能了。

示例1：获取文档内容

用户指令：“读取飞书文档docx_xxx的内容”

AI会调用get_feishu_doc_raw工具：

{
  "docId": "docx_xxx"
}

示例2：获取文档元数据

用户指令：“获取文档docx_xxx的元数据信息”

AI会调用get_feishu_doc_info工具，返回文档的创建时间、所有者等信息。

示例3：发送文本消息

用户指令：“向群聊oc_xxx发送消息‘大家好，我是AI助手’”

AI会调用send_feishu_text_message工具：

{
  "chatId": "oc_xxx",
  "text": "大家好，我是AI助手"
}

示例4：发送交互卡片

用户指令：“向群聊发送一个包含按钮的交互卡片”

AI会调用send_feishu_card工具，传入JSON格式的卡片内容。

示例5：获取聊天信息

用户指令：“获取群聊oc_xxx的基本信息”

AI会调用get_feishu_chat_info工具。

示例6：多维表格操作

获取表格元数据：

{
  "appToken": "base_xxx"
}

获取数据表列表：

{
  "appToken": "base_xxx",
  "pageSize": 20
}

获取视图列表：

{
  "appToken": "base_xxx",
  "tableId": "tbl_xxx"
}

获取记录：

{
  "appToken": "base_xxx",
  "tableId": "tbl_xxx",
  "viewId": "view_xxx",
  "pageSize": 10
}

示例7：STDIO模式运行

NODE_ENV=cli node dist/index.js

或

node dist/index.js --stdio

六、常见问题

问题1：认证失败

解决方案：

• 检查App ID和App Secret是否正确
• 确认应用已发布
• 确认应用具有所需的权限范围

问题2：令牌刷新失败

解决方案：

• 检查网络连接稳定性
• 设置更短的令牌缓存时间（TOKEN_CACHE_DURATION）

问题3：Node.js版本要求

解决方案：需要Node.js 23.0或更高版本。使用node -v检查版本。

问题4：文档ID如何获取？

解决方案：文档ID通常在飞书文档URL中，格式为https://feishu.cn/docx/xxx，其中xxx就是文档ID。

问题5：多维表格ID如何获取？

解决方案：多维表格ID在URL中，格式为https://feishu.cn/base/xxx或https://feishu.cn/app/xxx。

七、总结

MCP飞书服务是MCP生态中第一个专门为飞书平台设计的官方风格服务器。它提供了文档、消息、聊天、多维表格等核心功能的完整集成。

这个项目的最大价值在于：

1. 功能完整：覆盖文档、消息、聊天、多维表格等核心功能
2. 双模式支持：STDIO和HTTP两种运行模式
3. 分层架构：清晰的分层设计，易于扩展
4. 类型安全：完整的TypeScript类型定义
5. MIT许可证：可自由使用和修改

如果你是飞书用户，并且希望用AI来辅助办公，MCP飞书服务将极大地提升你的工作效率。