MCP 服务器

reasonix-feishu-mcp

MCP server for Feishu/Lark API integration, enabling AI agents to send messages, manage groups, create and edit documents and spreadsheets, and search knowledge bases.

README

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 文件管理。

飞书开放平台配置步骤

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

需要申请的权限

权限	用途	代码中对应的 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`	打包配置