reasonix-feishu-mcp 🚀

飞书 Feishu/Lark MCP Server — 完整的飞书 API MCP 实现
支持 AI 代理通过 MCP 协议直接操控飞书：收发消息、管理群组、操作文档、编辑表格、管理云盘、搜索知识库。

---

✨ 功能一览

类别	工具	说明
💬 消息	feishu_send_text	发送文本消息
	feishu_send_image	发送图片（自动上传）
	feishu_send_file	发送文件（自动上传）
	feishu_list_messages	查看群聊最近消息
	feishu_download_file	下载消息中的图片/文件
👥 群组	feishu_list_chats	列出所有群聊
	feishu_get_chat_members	获取群成员列表
📄 文档	feishu_create_doc	创建云文档
	feishu_get_doc_content	获取文档纯文本
	feishu_upload_local_file	上传本地文件并转为云文档
📊 电子表格	feishu_create_sheet	创建电子表格
	feishu_read_sheet	读取表格数据
☁️ 云空间	feishu_list_drive_files	列出云盘文件
🔍 知识库	feishu_search_wiki	搜索知识库

---

🔐 前置条件：飞书应用配置

在使用之前，你需要在 飞书开放平台 创建一个企业自建应用，并获取以下凭证：

需要设置的凭证（环境变量）

运行本 MCP 服务器需要配置以下环境变量：

环境变量	必填	说明	获取位置
FEISHU_APP_ID	✅ 是	飞书应用的 App ID	开放平台 → 应用 → 凭证与基础信息
FEISHU_APP_SECRET	✅ 是	飞书应用的 App Secret	开放平台 → 应用 → 凭证与基础信息
FEISHU_VERIFICATION_TOKEN	❌ 否（卡片回调才需要）	飞书应用的 Verification Token	开放平台 → 应用 → 事件与回调
PYTHONIOENCODING	✅ 推荐	设为 utf-8，防止中文乱码	—

⚠️ 安全提醒：FEISHU_APP_SECRET 和 FEISHU_VERIFICATION_TOKEN 属于敏感信息，切勿提交到 Git 仓库。建议通过环境变量或 .env 文件管理。

飞书开放平台配置步骤

1. 前往 飞书开放平台 → 我的应用 → 创建企业自建应用
2. 在 「凭证与基础信息」 页面获取 App ID 和 App Secret
3. 在 「安全设置」 页面设置重定向 URL（如需要）
4. 在 「事件与回调」 → 「卡片回调」 页面获取 Verification Token（如需卡片交互功能）
5. 在 「权限管理」 中添加所需权限（见下方列表），并发布应用

需要申请的权限

权限	用途	代码中对应的 API
im:message:send_as_bot	发送消息	send_message
im:message:readonly	读取消息列表	list_messages
im:resource:readonly	下载图片/文件	download_image, download_file
im:chat:readonly	查看群列表/成员	list_chats, get_chat_members
docx:document:create	创建文档	create_doc
docx:document_content:readonly	读取文档内容	get_doc_content
sheet:sheet:create	创建表格	create_sheet
sheet:sheet_content:readonly	读取表格数据	read_sheet
drive:drive:readonly	列出云盘文件	list_drive_files
drive:drive:upload_file	上传文件到云盘	upload_file_to_drive
wiki:wiki:readonly	搜索知识库	search_wiki

---

🚀 快速开始

方式一：直接运行（推荐）

# 1. 克隆仓库
git clone https://github.com/Monc618/reasonix-feishu-mcp.git
cd reasonix-feishu-mcp

# 2. 安装依赖
pip install requests

# 3. 设置环境变量（Windows PowerShell）
$env:FEISHU_APP_ID = "cli_xxxxxxxxxxxxxx"
$env:FEISHU_APP_SECRET = "your_app_secret_here"

# 3. 设置环境变量（Linux / macOS）
export FEISHU_APP_ID="cli_xxxxxxxxxxxxxx"
export FEISHU_APP_SECRET="your_app_secret_here"

# 4. 启动 MCP 服务器
python feishu-mcp-server.py

方式二：通过 Reasonix / Claude Code 配置

在 .mcp.json 中添加（参考 .mcp.example.json）：

{
  "mcpServers": {
    "feishu-mcp": {
      "command": "python",
      "args": ["path/to/feishu-mcp-server.py"],
      "env": {
        "FEISHU_APP_ID": "${FEISHU_APP_ID}",
        "FEISHU_APP_SECRET": "${FEISHU_APP_SECRET}",
        "FEISHU_VERIFICATION_TOKEN": "${FEISHU_VERIFICATION_TOKEN}",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

你的 Shell 环境中需要有对应的环境变量（FEISHU_APP_ID、FEISHU_APP_SECRET 等），MCP 客户端会自动注入。

方式三：pip 安装

pip install git+https://github.com/Monc618/reasonix-feishu-mcp.git

---

📖 工具使用示例

发送文本消息

{
  "name": "feishu_send_text",
  "arguments": {
    "receive_id": "oc_xxxxxxxxxxxxx",
    "receive_id_type": "open_id",
    "text": "你好，世界！"
  }
}

发送图片

{
  "name": "feishu_send_image",
  "arguments": {
    "receive_id": "oc_xxxxxxxxxxxxx",
    "image_path": "/path/to/image.png"
  }
}

创建云文档

{
  "name": "feishu_create_doc",
  "arguments": {
    "title": "我的新文档"
  }
}

上传文件并转为云文档

{
  "name": "feishu_upload_local_file",
  "arguments": {
    "file_path": "C:/Users/xxx/Desktop/报告.docx"
  }
}

---

📁 文件说明

文件	说明
feishu-mcp-server.py	★ 主 MCP 服务器（15 个飞书 API 工具）
feishu-card-handler.py	卡片回调 WebSocket 处理器（需 lark-oapi）
feishu-webhook.py	卡片回调 HTTP Webhook 服务
card_callback_server.py	备用简易回调服务
.mcp.example.json	MCP 配置模板（占位符代替真实密钥）
requirements.txt	Python 依赖
setup.py	打包配置

---

🛠️ 技术栈

• 协议：MCP (Model Context Protocol) via JSON-RPC 2.0 over stdio
• 运行时：Python 3.8+
• 核心依赖：requests（仅此一个）
• 可选依赖：lark-oapi（卡片回调 WebSocket 模式）

---

📄 许可证

MIT License

---

🌟 相关项目

• Efficient-Reasonix — Reasonix 高效使用指南（MCP 服务配置、多模态接入、自定义 Skill）