Metadata-Version: 2.4
Name: feishu-mcp
Version: 0.2.2
Summary: A safe Feishu MCP server for task-delivery notifications
Author: Internal Platform Team
License-Expression: LicenseRef-Proprietary
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp<2.0.0,>=1.0.0

# 飞书 MCP

这是一个通过 MCP 向飞书用户或群聊发送文本、文件的工具。它支持按名称查找收件人，并会将已成功发送的目标缓存到本机，以减少重复查询。

## 开始使用

### 1. 安装 uv

选择与你的操作系统对应的安装方式：

**Windows（PowerShell）**

```powershell 官方脚本
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

```powershell win自带包管理器
winget install --id=astral-sh.uv -e
```

**macOS（终端，需已安装 Homebrew）**

```bash
brew install uv
```

**Linux（终端）**

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

安装完成后，重新打开终端或 Amazon Quick，确认命令可用：

```bash
uvx --version
```

### 2. 配置 MCP 客户端

在 Amazon Quick 中打开 **Settings → Capabilities → MCP Servers**，创建MCP Server → Paste JSON。

```json
{
  "mcpServers": {
    "feishu": {
      "command": "uvx",
      "args": ["--from", "feishu-mcp==0.2.2", "feishu-mcp"],
      "description": "向飞书用户或群聊发送消息和文件，支持按名称查找收件人。",
      "env": {
        "FEISHU_APP_ID": "你的飞书应用 App ID",
        "FEISHU_APP_SECRET": "你的飞书应用 App Secret"
      }
    }
  }
}
```

保存配置并重启 MCP 客户端。首次启动时，`uvx` 会自动下载工具及其依赖；之后会复用本机缓存。

## 使用方式

配置完成后，可以直接让支持 MCP 的客户端完成以下操作：

- 查找飞书用户或群聊：`查询用户“张三”`、`查询群聊“研发部门”`
- 发送消息：`向李四发送：项目已完成。`
- 发送文件：`将 D:\\报告.xlsx 发送给李四`

如果同名用户或群聊有多个匹配项，工具不会猜测收件人，而会提示你提供更准确的名称或直接提供飞书 `open_id` / `chat_id`。

## 飞书应用要求

使用前需要创建并启用一个飞书自建应用，并将它的 `App ID` 与 `App Secret` 填入 MCP 配置。应用还需申请与实际功能匹配的通讯录、消息发送、文件上传权限；若要按群聊名称查询，还需要 `im:chat:readonly` 权限。

请勿将 `App Secret` 写入代码、上传到仓库，或发送给他人。

## 更新

将配置中 `feishu-mcp==` 后的版本号改为新版本，重启 MCP 客户端即可更新。建议始终固定版本号，方便回滚和排查问题。
