# feishu-bot-mcp

飞书机器人 MCP 服务器 — 通过 [Model Context Protocol](https://modelcontextprotocol.io/) 向飞书发送文本、文件和图片消息。

适用于 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. 创建 [飞书开放平台](https://open.feishu.cn/) 应用，获取 App ID 和 App Secret
2. 为应用开启 **机器人** 能力
3. 添加权限：`im:message:send_as_bot`、`im:file`、`im:image`
4. 将机器人添加到目标群组

## 安装

```bash
# 克隆项目
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`，填入你的飞书应用凭证：

```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

```bash
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`：

```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 设置中添加：

```json
{
  "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