# 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` | 搜索知识库 |

---

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

在使用之前，你需要在 [飞书开放平台](https://open.feishu.cn) 创建一个企业自建应用，并获取以下凭证：

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

运行本 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. 前往 [飞书开放平台](https://open.feishu.cn) → 我的应用 → 创建企业自建应用
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` |

---

## 🚀 快速开始

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

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

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

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

---

## 📖 工具使用示例

### 发送文本消息

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

### 发送图片

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

### 创建云文档

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

### 上传文件并转为云文档

```json
{
  "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](https://github.com/meisijiya/Efficient-Reasonix) — Reasonix 高效使用指南（MCP 服务配置、多模态接入、自定义 Skill）