# feishu-mcp-server

**Repository Path**: valleyfo/feishu-mcp-server

## Basic Information

- **Project Name**: feishu-mcp-server
- **Description**: 该项目可以帮助LLM将信息发送到飞书群组。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-11
- **Last Updated**: 2026-02-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Feishu MCP Server

Feishu MCP Server 是一个 Model Context Protocol (MCP) 服务器，允许 AI 助手调用飞书相关工具，将指定信息发送到飞书群组。

## 概述

该服务器提供以下功能：
- 发送简单文本消息到飞书群组
- 发送富文本卡片消息到飞书群组
- 通过 webhook 与飞书开放平台集成
- 支持 HTTP 和 Streamable HTTP 传输模式（推荐用于生产环境）
- 已弃用 stdio 传输模式，推荐使用 Streamable HTTP 模式进行容器化部署

## 功能特性

- **MCP 兼容**: 与 Model Context Protocol 兼容，可与支持 MCP 的 AI 助手集成
- **异步处理**: 使用异步 HTTP 请求，提高性能
- **灵活配置**: 支持环境变量配置
- **错误处理**: 完善的错误处理和日志记录

## 环境要求

- Python 3.13+
- uv 包管理器 (或 pip)

## 安装

### 使用 uv (推荐)

```bash
# 安装依赖
uv sync

# 或者只安装运行时依赖
uv pip install -e .
```

### 使用 pip

```bash
# 安装依赖
pip install -e .
```

## 配置

在使用服务器之前，需要配置以下环境变量：

```bash
# 飞书群机器人的 Webhook URL (必需)
FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/your-webhook-url

# 机器人名称 (可选，默认为 "AI Assistant")
FEISHU_BOT_NAME=AI Assistant
```

### 如何获取飞书群机器人 Webhook URL

1. 在飞书群中添加自定义机器人
   - 打开飞书群聊
   - 点击右上角群设置
   - 选择 "群机器人"
   - 点击 "+ 添加机器人"
   - 选择 "自定义机器人"
   - 设置机器人名称和头像
   - 选择 "通过 Webhook 接入"
   - 复制 Webhook URL

## 使用方法

### 1. 启动 MCP 服务器

```bash
# HTTP 传输模式（推荐用于容器化部署）
python -m feishu_mcp_server http 3000

# Streamable HTTP 传输模式（推荐用于 MCP 客户端集成，特别是生产环境）
python -m feishu_mcp_server streamable_http 3000

# 默认情况下，如果不指定传输模式，将使用 streamable_http
python -m feishu_mcp_server
```

### 2. 与 MCP 客户端集成

在 MCP 配置文件中添加以下配置：

#### HTTP 传输模式（生产环境/容器化部署）

```json
{
  "mcpServers": {
    "feishu-mcp-server": {
      "command": "python",
      "args": [
        "-m",
        "feishu_mcp_server",
        "http",
        "3000"
      ],
      "transport": "http",
      "url": "http://localhost:3000/mcp",
      "disabled": false
    }
  }
}
```

#### Streamable HTTP 传输模式（推荐用于 MCP 客户端集成，特别是生产环境）

```json
{
  "mcpServers": {
    "feishu-mcp-server": {
      "command": "python",
      "args": [
        "-m",
        "feishu_mcp_server",
        "streamable_http",
        "3000"
      ],
      "transport": "streamable_http",
      "url": "http://localhost:3000/mcp",
      "disabled": false
    }
  }
}
```

### 3. 可用工具

#### send_feishu_message

发送消息到飞书群组

参数:
- `webhook_url` (string, 可选): 飞书 webhook URL (可选，如果未提供则使用环境变量)
- `message` (string, 必需): 要发送的文本消息
- `title` (string, 可选): 消息卡片的标题 (默认: "AI Assistant Notification")
- `message_type` (string, 可选): 消息类型 ('text' 或 'post') (默认: 'text')

示例:
```json
{
  "name": "send_feishu_message",
  "arguments": {
    "message": "这是一个来自 AI 助手的测试消息",
    "title": "系统通知"
  }
}
```

#### send_feishu_card_message

发送富文本卡片消息到飞书群组

参数:
- `webhook_url` (string, 可选): 飞书 webhook URL (可选，如果未提供则使用环境变量)
- `title` (string, 必需): 卡片消息的标题
- `content` (string, 必需): 卡片消息的主要内容
- `image_url` (string, 可选): 要包含在卡片中的图片 URL
- `author` (string, 可选): 消息作者/来源 (默认: "AI Assistant")

示例:
```json
{
  "name": "send_feishu_card_message",
  "arguments": {
    "title": "重要通知",
    "content": "这是一条重要通知内容",
    "author": "系统通知"
  }
}
```

## 示例

### 发送简单文本消息

```json
{
  "name": "send_feishu_message",
  "arguments": {
    "message": "早上好！这是一个问候消息",
    "title": "问候"
  }
}
```

### 发送富文本卡片消息

```json
{
  "name": "send_feishu_card_message",
  "arguments": {
    "title": "项目更新",
    "content": "项目 v1.0 已发布，包含以下新功能：\n- 功能A\n- 功能B\n- 功能C",
    "author": "系统机器人"
  }
}
```

## 开发

### 运行测试

```bash
python test_feishu_mcp.py
```

### 项目结构

```
feishu_mcp_server/
├── feishu_mcp_server.py   # 主服务器实现
├── logger_config.py       # 日志配置
├── README.md             # 项目说明
├── pyproject.toml        # 项目配置
└── .env                  # 环境变量配置 (本地)
```

## 依赖

- aiohttp: 用于异步 HTTP 请求
- httpx: HTTP 客户端库
- mcp: Model Context Protocol 支持
- python-dotenv: 环境变量加载

## 故障排除

### 常见问题

1. **无法发送消息**
   - 检查 `FEISHU_WEBHOOK_URL` 是否正确配置
   - 确认机器人仍在群组中
   - 检查网络连接

2. **环境变量未生效**
   - 确认 `.env` 文件格式正确
   - 检查环境变量名称拼写

3. **服务器无法启动**
   - 确认 Python 版本满足要求
   - 检查依赖是否正确安装

## 在 k3s/Kubernetes 中部署

Feishu MCP Server 可以部署在 k3s 或 Kubernetes 环境中，推荐使用 Streamable_HTTP 传输模式：

### 部署注意事项

1. **传输模式**: 在 k3s/Kubernetes 环境中，必须使用 HTTP 或 Streamable HTTP 传输模式（stdio 模式已被弃用）
2. **安全性**: 使用 Kubernetes Secrets 存储敏感信息，如 webhook URL
3. **服务暴露**: 通过 Service 暴露服务给其他组件
4. **健康检查**: 配置适当的健康检查探针
5. **资源限制**: 设置适当的资源请求和限制

## 许可证

MIT