feishu-bot-mcp

飞书机器人 MCP 服务器 — 通过 Model Context Protocol 向飞书发送文本、文件和图片消息。

适用于 Claude Code、AionUI 等支持 MCP 的 AI 工具。

功能

工具	说明
feishu_send_text_message	发送文本消息
feishu_send_file	上传并发送文件
feishu_send_image	上传并发送图片
feishu_upload_file_only	仅上传文件（返回 file_key）
feishu_send_uploaded_file	发送已上传的文件
feishu_send_uploaded_image	发送已上传的图片

所有发送类工具的 receive_id 参数均可留空，自动使用 .env 中配置的默认群组。

前置条件

1. 创建 飞书开放平台 应用，获取 App ID 和 App Secret
2. 为应用开启 机器人 能力
3. 添加权限：im:message:send_as_bot、im:file、im:image
4. 将机器人添加到目标群组

安装

# 克隆项目
git clone https://github.com/<your-username>/feishu-bot-mcp.git
cd feishu-bot-mcp

# 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
# 编辑 .env 填入真实凭证

配置

复制 .env.example 为 .env，填入你的飞书应用凭证：

# 飞书应用凭证（必填）
FEISHU_APP_ID=your_app_id_here
FEISHU_APP_SECRET=your_app_secret_here

# 默认消息接收群组 ID（选填）
FEISHU_CHAT_ID=your_chat_id_here

配置优先级：环境变量 > .env 文件 > 调用时传参

MCP 集成配置

Claude Code

claude mcp add -s user \
  -e "FEISHU_CHAT_ID=your_chat_id" \
  -- feishu-bot \
  /path/to/.venv/bin/python3 \
  /path/to/feishu-bot-mcp/server.py

或手动编辑 ~/.claude.json：

{
  "mcpServers": {
    "feishu-bot": {
      "command": "/path/to/.venv/bin/python3",
      "args": ["/path/to/feishu-bot-mcp/server.py"],
      "env": {
        "FEISHU_CHAT_ID": "your_chat_id"
      }
    }
  }
}

AionUI

在 MCP 设置中添加：

{
  "feishu-bot": {
    "command": "/path/to/.venv/bin/python3",
    "args": ["/path/to/feishu-bot-mcp/server.py"],
    "env": {
      "FEISHU_CHAT_ID": "your_chat_id"
    }
  }
}

注意：如果 .env 文件已配置好凭证，MCP 配置中的 env 字段可以省略。环境变量会覆盖 .env 中的值。

使用示例

配置完成后，在 AI 工具中可以直接使用：

# 发送文本（自动发到默认群组）
→ feishu_send_text_message(text="Hello from MCP!")

# 发送文件
→ feishu_send_file(file_path="/path/to/report.pdf")

# 发送图片
→ feishu_send_image(image_path="/path/to/screenshot.png")

# 发送到指定群组
→ feishu_send_text_message(text="Hi", receive_id="oc_xxx")

支持的文件类型

file_type	说明
stream	通用二进制流（默认）
pdf	PDF 文档
doc	Word 文档
xls	Excel 表格
ppt	PowerPoint 演示文稿
mp4	视频文件
opus	音频文件

License

MIT