使用说明

项目简介

飞书 MCP 服务器是一个基于 Model Context Protocol 的应用后端，旨在为大型语言模型（LLM）客户端提供与飞书（原 Lark）集成的上下文信息和功能。通过此服务器，LLM 可以安全、可扩展地访问和操作飞书平台上的文档、机器人和聊天等资源，实现更智能的应用场景。

主要功能点

文档服务：允许 LLM 读取飞书文档的原始内容和元数据信息，例如文档内容提取、文档信息查询等。
机器人服务：支持 LLM 控制飞书机器人发送文本消息和交互式卡片消息到指定的飞书群组或个人，实现消息触达和互动。
聊天服务：提供飞书群组和聊天会话的管理能力，例如搜索群组信息等，帮助 LLM 理解和利用聊天上下文。
多模式支持：
- STDIO 模式：通过标准输入/输出进行通信，适用于命令行环境或集成到其他程序中。
- HTTP 模式：提供 HTTP REST API 和 SSE (Server-Sent Events) 连接，适用于 Web 服务和分布式部署，方便 LLM 客户端通过 HTTP 协议连接。
完善的错误处理：提供统一的错误处理机制，能够返回详细的错误信息，方便 LLM 客户端进行错误排查和处理。

安装步骤

克隆仓库

git clone https://github.com/sdd330/feishu-mcp-server.git
cd feishu-mcp-server

安装依赖

确保已安装 Node.js (>=23.0) 和 pnpm 包管理器。然后运行：
```
pnpm install
```

配置环境变量

复制仓库中的 '.env.example' 文件并重命名为 '.env'，根据提示填写飞书自建应用的 App ID 和 App Secret。

FEISHU_APP_ID=your_app_id
FEISHU_APP_SECRET=your_app_secret

服务器配置

MCP 客户端需要配置以下 JSON 信息以连接到飞书 MCP 服务器。请根据您选择的运行模式配置 'command' 和 'args'。

STDIO 模式配置

{
  "serverName": "FeishuMCP-Stdio",
  "command": "node",
  "args": ["dist/index.js", "--stdio"]
}

HTTP 模式配置

{
  "serverName": "FeishuMCP-Http",
  "command": "node",
  "args": ["dist/index.js"],
  "transport": "sse",
  "endpoint": "http://localhost:3344/sse"
}

配置参数说明:

'serverName': MCP 服务器的名称，可以自定义。
'command': 启动 MCP 服务器的命令，这里使用 'node' 运行 JavaScript 代码。
'args': 传递给启动命令的参数。
- STDIO 模式: '["dist/index.js", "--stdio"]' 指定运行编译后的 'index.js' 文件，并使用 '--stdio' 参数启用 STDIO 模式。
- HTTP 模式: '["dist/index.js"]' 指定运行编译后的 'index.js' 文件，默认启动 HTTP 模式。
'transport': (仅 HTTP 模式) 使用的传输协议，这里为 'sse' (Server-Sent Events)。
'endpoint': (仅 HTTP 模式) SSE 连接的端点 URL，默认为 'http://localhost:3344/sse'，端口号 '3344' 是默认配置，可以在 '.env' 文件中通过 'PORT' 变量修改。

注意:

飞书应用需要配置为 自建应用，并获取 App ID 和 App Secret。
确保飞书应用已开通文档、机器人 和 通讯录 (用于聊天功能) 相关 API 的权限。
HTTP 模式默认端口为 '3344'，可以通过设置环境变量 'PORT' 或命令行参数 '--port' 修改。

基本使用方法

启动服务器

根据您选择的模式，运行相应的命令启动飞书 MCP 服务器。
- 开发模式 (HTTP): 'pnpm dev'
- 生产模式 (HTTP): 'pnpm start' 或 'node dist/index.js'
- STDIO 模式: 'NODE_ENV=cli node dist/index.js' 或 'node dist/index.js --stdio'
在 MCP 客户端中使用工具

在 LLM 的 MCP 客户端中，您可以调用以下工具来与飞书进行交互：
- 'get_feishu_doc_raw': 获取飞书文档的原始内容，参数为 'docId' (文档 ID)。
- 'get_feishu_doc_info': 获取飞书文档的元数据信息，参数为 'docId' (文档 ID)。
- 'send_feishu_text_message': 发送文本消息到飞书聊天，参数为 'chatId' (聊天 ID) 和 'text' (消息内容)。
- 'send_feishu_card': 发送交互卡片到飞书聊天，参数为 'chatId' (聊天 ID) 和 'cardContent' (卡片 JSON 字符串)。
- 'search_chats': 搜索飞书群组，参数可以包括 'query' (搜索关键词) 等。
- 'get_chats': 获取用户或机器人所属的飞书群组列表。
例如，在 MCP 客户端中，您可以使用 'get_feishu_doc_raw' 工具来读取指定飞书文档的内容，并将其作为上下文提供给 LLM 进行后续处理。

关键词