lark-mcp-bridge

# lark-mcp-bridge 将 [lark-cli](https://github.com/larksuite/cli)（飞书/Lark 官方 CLI）封装为 [MCP](https://modelcontextprotocol.io/) Server，使 AI 助手能够操作飞书。 支持飞书（中国版）和 Lark（国际版），取决于 lark-cli 配置。当前仅在飞书环境下验证。 ## 背景 AI 工作助手（如 Amazon Quick、Claude Desktop、Anthropic Coworker）出于安全设计，不能直接执行 shell 命令或调用外部 API。它们通过 MCP 协议扩展能力——MCP 是这类助手连接外部服务的唯一通道。本项目让这类助手能够操作飞书。 对于有终端权限的编码工具（Claude Code、Cursor 等），同样可以通过 MCP 获得结构化的飞书操作能力，无需自行解析 CLI 输出。 ## 特点 - **无需创建飞书应用** — 复用 lark-cli 的个人登录态，无需 App ID/Secret - **14 个域、219 个 API** — 通过 `lark.discover` 元工具让 Agent 按需探索，不受固定工具列表限制 - **安全白名单** — 默认拒绝未审核操作，风险分级，破坏性操作需确认 - **结构化交互** — 每个操作提供完整 JSON Schema（参数名、类型、枚举、必填），Agent 不需要猜参数 - **统一错误处理** — 分类错误码（认证过期、限流、权限不足…）+ 中文恢复建议，而非裸 stderr - **上下文友好** — schema 按需加载，不会一次性灌入大量 help 文本占用 Agent 上下文窗口 - **标准 MCP 协议** — 兼容任何 MCP 客户端（Amazon Quick、Claude、Cursor、opencode 等） ## 前置条件 - Python 3.12+ - [lark-cli](https://github.com/larksuite/cli) 已安装并完成登录（`lark-cli auth login`） ## 安装 ```bash pip install lark-mcp-bridge # 或开发模式 git clone https://github.com/YOUR_USERNAME/lark-mcp-bridge.git cd lark-mcp-bridge pip install -e ".[dev]" ``` ## 使用 ### 启动 Server ```bash python -m lark_mcp_bridge.server ``` ### MCP 客户端配置 所有客户端的配置本质相同： ```json { "mcpServers": { "lark": { "command": "python", "args": ["-m", "lark_mcp_bridge.server"] } } } ``` - **Amazon Quick Desktop**: Settings → Capabilities → MCP → Add Local - **Claude Code / Claude Desktop**: `~/.claude/mcp.json` - **Cursor**: Settings → MCP Servers → Add (type: command) - **opencode**: `opencode.json` ## 工作原理 ``` AI 客户端 ⇄ MCP (stdio) ⇄ lark-mcp-bridge ⇄ lark-cli ⇄ 飞书 API ``` bridge 不直接调用飞书 HTTP API。认证和 token 管理由 lark-cli 处理，你的 credential 不经过第三方。 ### 内置工具 | 工具 | 功能 | |------|------| | `lark.im.messages-send` | 发送消息 | | `lark.calendar.agenda` | 查看日程 | | `lark.calendar.schedule-meeting` | 预约会议 | | `lark.base.record-search` | 搜索多维表格 | | `lark.docs.fetch` | 读取文档 | | `lark.contact.search-user` | 搜索联系人 | | `lark.sheets.read` | 读取电子表格数据 | |…