Sean's Blog

Claude Code 集成飞书文档方案

11分钟阅读

Claude Code 集成飞书文档方案

通过飞书官方 MCP 实现 Claude Code 与飞书云文档的集成

方案概述

Claude Code 与飞书的集成分两个方向：

  • 主动调用（本文）：Claude Code 通过 Lark MCP 主动调用飞书 API（发消息、读文档、操作多维表格）
  • 被动响应：飞书群成员 @Bot 发指令，Bot 自动响应——需额外部署 cc-connect，见 cc-connect 飞书接入实践

本文介绍主动调用方案。使用飞书官方提供的 lark-openapi-mcp 是目前最成熟的集成方案。该工具将飞书开放平台 API 封装为 MCP 工具，支持文档处理、会话管理、日历安排等自动化场景。

前置要求

  • Node.js LTS 版本（验证：node -v 和 npm -v）
  • 飞书账号（企业版或个人版）
  • Claude Code 已安装

配置步骤

第一步：创建飞书应用

  1. 访问飞书开放平台

  2. 创建企业自建应用

    • 进入「开发者后台」→「创建应用」→「企业自建应用」
    • 填写应用名称（如 Claude-MCP-Bot）和应用描述
    • 记录 App ID 和 App Secret（在「凭证与基础信息」页面获取）

  3. 添加机器人能力

    • 进入「应用能力」→ 添加「机器人」卡片
    • 确保机器人处于启用状态（不仅是添加）

第二步：配置应用权限

在「权限管理」页面按需添加权限（遵循最小权限原则）：

云文档权限（必需）

权限名称权限标识说明
查看、评论和导出文档docx:document:readonly只读访问文档
查看、评论、编辑和管理文档docx:document完整文档操作
查看云空间文件信息drive:drive:readonly浏览云空间
查看文档 wiki 信息wiki:wiki:readonly访问知识库

消息与群组权限（可选）

权限名称权限标识说明
获取与发送单聊、群组消息im:message消息读写
获取群组信息im:chat:readonly查看群组

多维表格权限（可选）

权限名称权限标识说明
查看、评论、编辑和管理多维表格bitable:bitable多维表格操作

权限审批

部分权限需要企业管理员审批，调试阶段可先开通免审核权限（如「查看文档」）。 权限变更后需要重新创建版本并发布才能生效。

第三步：配置重定向 URL（OAuth 模式需要）

  1. 进入应用的「安全设置」→「重定向 URL」
  2. 添加以下地址：
http://localhost:3000/callback
  1. 点击「添加」保存

第四步：设置可用范围并发布

  1. 进入「应用发布」→「可用范围」，添加需要使用该应用的人员/部门
  2. 点击页面顶部的「创建版本」
  3. 填写版本信息（版本号、更新说明等）
  4. 提交发布
    • 个人版应用：可免审发布
    • 企业版应用：需等待管理员审批

第五步：配置 Claude Code

在项目 .mcp.json 或全局 ~/.claude/.mcp.json 中添加配置。

应用身份模式（推荐开发场景）

{
  "mcpServers": {
    "lark-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@larksuiteoapi/lark-mcp",
        "mcp",
        "-t", "preset.doc.default,preset.im.default",
        "-l", "zh"
      ],
      "env": {
        "APP_ID": "<你的App_ID>",
        "APP_SECRET": "<你的App_Secret>"
      }
    }
  }
}

安全建议

使用 env 字段传递密钥，避免明文写在 args 中。

用户身份模式（需先登录授权）

npx -y @larksuiteoapi/lark-mcp login \
  -a <你的App_ID> \
  -s <你的App_Secret> \
  --scope offline_access docx:document im:message

然后配置中添加 OAuth 参数：

{
  "mcpServers": {
    "lark-mcp": {
      "command": "npx",
      "args": [
        "-y", "@larksuiteoapi/lark-mcp", "mcp",
        "-a", "<你的App_ID>",
        "-s", "<你的App_Secret>",
        "--oauth",
        "--token-mode", "user_access_token"
      ]
    }
  }
}

第六步：验证配置

重启 Claude Code 后，执行 /mcp 确认 lark-mcp 状态为已连接。

Token 模式对比

维度应用身份 (tenant_access_token)用户身份 (user_access_token)
含义以应用/租户身份调用 API以个人身份调用 API
能访问什么应用被授权的资源（被共享的文档、应用所在群）个人能看到的所有资源（个人文档、日历等）
典型场景Bot 发通知、操作多维表格读个人文档、查个人日历
配置复杂度简单，只需 App ID + Secret需额外 OAuth 登录
Token 续期自动续期需 offline_access scope 保持有效

选择建议

  • 大多数开发场景用应用身份即可 — 读写项目文档、往群里发通知、操作多维表格
  • 需要访问个人私有资源时才用用户身份 — 如个人空间中未共享的文档
  • 设置 --token-mode auto（默认）可根据 API 自动选择

预设工具集

通过 -t 参数指定启用的工具集（减少 token 消耗），可用逗号组合多个预设和单个 API：

-t preset.doc.default,preset.im.default,calendar.v4.calendarEvent.create
预设名包含工具适用场景
preset.light发消息、搜索文档/群、查多维表格、获取用户ID最精简，token 敏感场景
preset.defaultlight 基础上 + 创建群/表格、管理群成员、wiki搜索、权限管理通用场景（默认）
preset.im.default创建群、群列表、群成员、收发消息纯 IM 场景
preset.doc.default文档内容读取、导入、搜索、wiki、权限管理纯文档场景
preset.base.default创建表格/数据表、字段列表、搜索/创建/更新记录多维表格基础操作
preset.base.batch类似 base.default，使用批量创建/更新多维表格批量操作
preset.task.default创建/修改任务、添加成员/提醒任务管理
preset.calendar.default创建/修改/查看日程、空闲查询、主日历日历管理

开发场景推荐

preset.doc.default,preset.im.default — 覆盖读文档 + 发消息，够用且不浪费 token。

命令行参数

参数说明推荐值
-aApp IDcli_xxx
-sApp Secret-
-t启用的工具集preset.doc.default,preset.im.default
-l / --language工具描述语言zh（中文环境）
--oauth启用用户身份认证-
--token-modeToken 类型user_access_token / tenant_access_token / auto
--domainAPI 域名国内默认 https://open.feishu.cn，海外用 https://open.larksuite.com
--tool-name-case工具名格式snake（默认）
--mode传输模式stdio（Claude Code 用默认即可）
--config配置文件路径./config.json

配置优先级：命令行参数 > 环境变量 > 配置文件 > 默认值

Bot 入群排查清单

将 Bot 添加到群聊时，如果在群设置中搜索不到机器人，逐一检查：

  1. 应用是否已发布 — 开发者后台「版本管理与发布」，必须有状态为「已发布」的版本
  2. 是否添加了机器人能力 — 「应用能力」中需要有「机器人」卡片且已启用
  3. 可用范围是否包含自己 — 「应用发布」→「可用范围」中需包含当前用户
  4. 搜索方式 — 尝试完整名称或关键词，或直接滚动列表查找

功能支持

功能支持情况说明
读取云文档内容✅ 支持获取文档全文内容
导入文档✅ 支持通过导入方式更新文档
搜索文档✅ 支持按关键词搜索
发送消息✅ 支持单聊、群聊消息
日历管理✅ 支持创建、查看日程
群组管理✅ 支持创建群、获取成员
多维表格操作✅ 支持记录的增删改查
知识库访问✅ 支持读取 Wiki 内容
直接编辑文档❌ 不支持只能通过导入覆盖
文件上传/下载❌ 不支持当前版本限制

常见问题

问题解决方案
权限不足检查应用权限是否开通并审批通过
Token 过期重新执行 login 命令授权
无法读取文档确保文档对应用/用户有访问权限
国际版 Lark添加 --domain https://open.larksuite.com 参数
npx 执行失败检查 Node.js 版本，建议使用 LTS 版本
授权页面打不开检查重定向 URL 是否正确配置
群里搜不到 Bot见上方「Bot 入群排查清单」

其他方案

远程 MCP 模式（Beta）

飞书提供 远程 MCP Server，无需本地部署，支持云端一键集成。

第三方 MCP 工具

参考链接

目录

关系图谱

反向链接