sai-feishu-mcp

一个面向飞书（Lark）的 MCP（Model Context Protocol）服务器。以 stdio 方式运行，把飞书开放平台的常用能力封装成一组工具，供支持 MCP 的 AI 客户端调用，实现「用自然语言操作飞书」。

简介

• 走 用户身份（user_access_token） 为主，代表「本人」操作飞书，权限清晰、可控。
• 纯工具化设计，即插即用：在支持 MCP 的客户端中登记本服务即可使用，无需二次开发。
• 覆盖云文档、云盘、多维表格、电子表格、消息、日历、任务、通讯录、知识库、审批等常用场景。

主要功能

• 云盘与文件：文件/文件夹列举与创建、上传、下载、文档搜索。
• 文档导出到本地：export_and_download 一体化把飞书云文档导出为本地 docx/pdf/xlsx/csv（含知识库 Wiki 文档），供后续转换为 WPS 等本地格式。
• 云文档（Docx）：读取文档纯文本/块结构、创建文档、写入文本块与标题块。
• 多维表格（Bitable）：创建多维表格与数据表、字段与记录的增查改。
• 电子表格（Sheets）：读取/写入指定区域数据。
• 即时消息（IM）：发送/回复消息、会话列举、历史与消息搜索。
• 日历（Calendar）：日历与日程的列举、创建、忙闲查询。
• 任务（Task）：任务创建、成员管理、更新与列举。
• 通讯录（Contact）：查询用户与部门信息。
• 知识库（Wiki）：节点与空间的查询、创建、移动。
• 妙记（Minutes）：获取妙记信息。
• 审批（Approval）：
  • 查询审批实例列表与实例详情；
  • 单个审批同意/拒绝（不可逆写操作，多重安全保护：走用户身份、按 open_id+PENDING 精确定位本人待办任务、本地授权开关默认关闭并需用户明确授权后方可执行）。

说明：飞书官方仅支持导出 docx/doc/sheet/bitable 四类文档；幻灯片、思维笔记、妙记无导出接口，需改用 download_file 下载原始附件。

环境要求

• Python >= 3.12
• 已在飞书开放平台创建应用，并配置好对应能力的权限。

安装与运行

在支持 MCP 的客户端中，将本服务登记为一个 stdio MCP 服务器，启动命令如下。

推荐（用户自动升级，无需任何手动操作）：

uvx --refresh sai-feishu-mcp

--refresh 会让 uvx 每次启动时检查并拉取已发布的最新版本，因此发布新版后，用户重启客户端即可自动用上最新版，无需改配置、无需清缓存。

以 MCP 客户端配置为例（不锁版本 + --refresh）：

{
  "command": "uvx",
  "args": ["--refresh", "sai-feishu-mcp"]
}

为什么不锁版本号（如 sai-feishu-mcp@0.1.1）？ 锁版本会遇到两个对普通用户不友好的坑：① 刚发布时，PyPI 国内镜像（如清华源）尚未同步该版本，会报 “No solution found” 装不上；② uvx 会缓存“解析失败/旧版本”结果，用户既不知道、也无法去清缓存。用 --refresh 不锁版本可彻底规避。

或安装后运行（本地开发调试用）：

pip install sai-feishu-mcp
sai-feishu-mcp

上线前必做：打包与上传（发布到 PyPI）

每次发布新版本前，务必先递增 pyproject.toml 中的 version（PyPI 不允许覆盖同一版本号）。

# 1) 修改版本号：编辑 pyproject.toml，将 version 递增（如 0.1.1 -> 0.1.2）

# 2) 清理旧产物并重新打包
rm -f dist/*.whl dist/*.tar.gz
uv build

# 3) 上传到 PyPI（执行后按提示粘贴 API token）
uv run python -m twine upload dist/*

发布成功后可在 https://pypi.org/project/sai-feishu-mcp/ 查看对应版本。

用户侧升级：只要客户端按上面的 uvx --refresh sai-feishu-mcp 配置，用户无需做任何操作，重启客户端即会自动拉取到本次发布的新版本。