Lark MCP + Claude Code 配置指南

让 Claude Code 通过 MCP 协议连接 Lark (飞书国际版)，实现文档读取、消息发送等功能。

---

前提条件

• Node.js 20+
• Claude Code CLI 已安装
• 你的组织使用 Lark (国际版飞书)

---

第一步：创建 Lark 应用

1. 打开 Lark Developer Console
2. 点击 Create Custom App
3. 填写应用名称和描述
4. 记下 App ID (cli_xxxxx) 和 App Secret

---

第二步：配置权限 (Permissions & Scopes)

进入权限配置页面

1. 打开 Lark Developer Console
2. 点击你的应用名称进入应用详情
3. 在左侧菜单栏，找到 Development Configuration 分组
4. 点击 Permissions & Scopes

你会看到一个权限配置页面，页面上方有说明文字，下方有两个按钮： - Add permission scopes to app — 添加权限 - Batch import/export scopes — 批量导入/导出

⚠️ 重要：选择正确的 Token 类型 Tab

页面中间有 两个 Tab（非常重要！）：

┌─────────────────────┬──────────────────────┐
│ Tenant token scopes │  User token scopes   │
└─────────────────────┴──────────────────────┘

• Tenant token scopes — 应用以"租户身份"调用 API（适合后台服务）
• User token scopes — 应用以"用户身份"调用 API（适合代表用户操作）

如果你的 MCP 配置使用 --token-mode user_access_token（本文档推荐的方式），必须点击 "User token scopes" Tab，在那里添加权限。

如何添加权限

1. 点击正确的 Tab（User token scopes）
2. 在右上角有一个 搜索框，输入你要添加的 scope 名称
3. 例如输入 bitable 可以找到所有 Bitable 相关权限
4. 例如输入 wiki 可以找到所有 Wiki 相关权限
5. 在搜索结果中，找到你需要的权限
6. 点击该权限右侧的 Add 按钮
7. 状态变为 Added 表示添加成功

左侧还有分类导航（All, Contacts, Organization, Messenger, Calendar, Docs, Rooms 等），Bitable 和 Wiki 权限都在 Docs 分类下。

推荐的权限配置

在 User token scopes Tab 中，搜索并添加以下权限：

核心权限（必须）

Scope	显示名称	功能
bitable:app	View, comment, edit and manage Base	Bitable 完整读写权限
wiki:wiki	View, edit, and manage Wiki	Wiki 完整读写权限

可选权限（按需添加）

Scope	显示名称	功能
bitable:app:readonly	View, comment, and export Base	Bitable 只读（更安全）
wiki:wiki:readonly	View all Wiki	Wiki 只读
wiki:node:read	View wiki space node information	查看 Wiki 节点信息
wiki:node:create	Create wiki space node	创建 Wiki 节点
wiki:space:read	View wiki space information	查看 Wiki 空间信息
docx:document	文档读写	读取/编辑文档内容
drive:drive	云盘读写	上传文件、管理权限
im:chat:readonly	消息只读	列出群聊、获取群成员

不需要的权限（可以跳过）

Scope	说明
vc:room / vc:room:readonly	视频会议室，MCP 工具不使用
admin:*	管理员权限，MCP 工具不使用
contact:*	通讯录权限，MCP 工具不使用
calendar:*	日历权限，MCP 工具不使用
email:*	邮件权限，MCP 工具不使用

安全建议：不要点 "All" 分类然后全选所有权限。只添加你需要的 scope。过多的权限 = 更大的安全风险。如果 App Secret 泄露，攻击者能做的事情越少越好。

当前已配置的权限示例

以下是一个完整配置示例（基于实际测试）：

Bitable 权限： - bitable:app — View, comment, edit and manage Base ✅ - bitable:app:readonly — View, comment, and export Base ✅

Wiki 权限： - wiki:wiki — View, edit, and manage Wiki ✅ - wiki:wiki:readonly — View all Wiki ✅ - wiki:node:read — View wiki space node information ✅ - wiki:node:create — Create wiki space node ✅ - wiki:node:retrieve — View wiki space node list ✅ - wiki:node:update — Update wiki space node information ✅ - wiki:space:read — View wiki space information ✅ - wiki:space:retrieve — View wiki space list ✅ - wiki:member:retrieve — View wiki space member list ✅

---

第三步：配置 OAuth 回调地址

1. 左侧菜单点击 Security Settings
2. 在 Redirect URLs 区域，添加：

http://localhost:3000/callback

1. 保存

---

第四步：让配置生效（二选一）

方案 A：测试模式（推荐，不需要审批）

1. 左侧菜单点击 Test Companies & Users
2. 把你自己加为测试用户
3. 配置立即生效

方案 B：正式发布（需要管理员审批）

1. 左侧菜单点击 Version Management & Release
2. 点击 Create Version
3. 填写版本号和更新说明
4. 提交后等待组织管理员审批

---

第五步：终端登录获取 Token

在终端运行：

npx -y @larksuiteoapi/lark-mcp login \
  -a <你的App ID> \
  -s <你的App Secret> \
  --domain https://open.larksuite.com

会发生什么

1. 终端显示：Opening browser for authentication... 或类似提示
2. 浏览器自动打开：跳转到 Lark 登录/授权页面
3. 登录你的 Lark 账号（如果还没登录）
4. 看到权限请求页面：显示应用名称和请求的权限列表
5. 点击"同意"或"Authorize"按钮
6. 浏览器显示成功页面：可以关闭浏览器
7. 回到终端：显示 Login successful! 或类似提示

⚠️ 重要提示

• 每次添加新权限后都要重新运行这个命令
• OAuth token 是快照——它只记录授权时的权限
• 如果你先运行 login，然后去添加新权限，新权限不会自动生效
• 正确顺序：先添加权限 → 再运行 login

登录失败怎么办

错误	原因	解决
redirect_uri is invalid	OAuth 回调地址未配置	检查第三步，确保添加了 http://localhost:3000/callback
浏览器显示 404	回调地址配置错误	同上
权限请求页面是空的	没有添加任何权限	先完成第二步，添加至少一个 scope

---

第六步：配置 Claude Code

编辑 ~/.claude/settings.json，在 mcpServers 中添加：

{
  "mcpServers": {
    "lark-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@larksuiteoapi/lark-mcp",
        "mcp",
        "-a", "<你的App ID>",
        "-s", "<你的App Secret>",
        "--domain", "https://open.larksuite.com",
        "--oauth",
        "--token-mode", "user_access_token"
      ]
    }
  }
}

注意：如果用飞书国内版，把 --domain 改为 https://open.feishu.cn

---

第七步：重启 Claude Code

关闭并重新打开 Claude Code，MCP 服务器会自动连接。

---

常见问题

错误	原因	解决
20029 redirect_uri request is invalid	Redirect URL 未配置或未发布生效	检查第三步和第四步
Token 过期	长时间未使用	重新运行第五步的 login 命令
权限不足 99991672	未添加所需 scope	见下方详细说明
WrongBaseToken	用 Bitable API 访问 Sheet 文档	见下方"文档类型"说明
NOTEXIST	文档 token 不正确	见下方"Wiki Token"说明

权限不足的排查步骤

如果看到错误 Access denied. One of the following scopes is required: [xxx]：

步骤 1：检查是否在正确的 Tab 添加了权限

1. 打开 Lark Developer Console → 你的应用
2. 左侧菜单点击 Permissions & Scopes
3. 查看页面顶部的 Tab：
4. 如果你在用 --token-mode user_access_token，必须点击 User token scopes Tab
5. 在搜索框搜索错误提示中的 scope（如 bitable:app）
6. 确认状态是 Added

步骤 2：添加权限后必须重新登录

这是最容易忽略的一步！OAuth token 是快照——它只包含授权时已有的 scope。

在终端运行：

npx -y @larksuiteoapi/lark-mcp login \
  -a <你的App ID> \
  -s <你的App Secret> \
  --domain https://open.larksuite.com

浏览器会弹出授权页面，重新点击同意。这会获取一个包含新权限的 token。

步骤 3：重启 Claude Code

关闭 Claude Code 窗口，重新打开。这会让 MCP 服务器重新加载，使用新获取的 token。

完整排查流程图

错误: Access denied, scope required: [bitable:app]
                    │
                    ▼
    ┌─────────────────────────────────┐
    │ 1. 打开 Lark Developer Console  │
    │    → Permissions & Scopes       │
    │    → User token scopes Tab      │
    │    → 搜索 bitable:app           │
    │    → 确认是 Added 状态          │
    └─────────────────────────────────┘
                    │
                    ▼
    ┌─────────────────────────────────┐
    │ 2. 终端运行 login 命令          │
    │    重新获取 OAuth token         │
    └─────────────────────────────────┘
                    │
                    ▼
    ┌─────────────────────────────────┐
    │ 3. 重启 Claude Code             │
    └─────────────────────────────────┘
                    │
                    ▼
              问题解决 ✅

文档类型说明

Lark 有多种文档类型，API 不通用：

类型	中文名	API	URL 特征
Bitable	多维表格	bitable/v1	/base/xxx
Sheet	电子表格	sheets/v3	/sheets/xxx 或 Wiki 中 obj_type: "sheet"
Docx	文档	docx/v1	/docx/xxx
Wiki	知识库	wiki/v2	/wiki/xxx

⚠️ Lark MCP 目前只支持 Bitable、Wiki、Docx，不支持 Sheet (电子表格)。如果你的文档是 Sheet，需要： - 手动导出为 CSV/Excel - 或将数据迁移到 Bitable

Wiki Token vs Document Token

Wiki 页面的 URL token 和实际文档 token 是不同的：

https://xxx.larksuite.com/wiki/Vq6OwsXGOi4lXJkxSBAjXVHdpCh
                              └── Wiki node token (用于 wiki API)

调用 wiki_v2_space_getNode 后会返回 obj_token，这才是实际文档的 token：

{
  "node_token": "Vq6OwsXGOi4lXJkxSBAjXVHdpCh",  // Wiki 节点
  "obj_token": "OtTgsAS2uhVxcitZtcFjgrgIpSb",   // 实际文档
  "obj_type": "sheet"                            // 文档类型
}

访问 Bitable 时，使用 obj_token 作为 app_token，而不是 URL 中的 wiki token。

---

安全提醒

App Secret 在 settings.json 中是明文存储的。更安全的做法是用环境变量：

{
  "command": "/bin/sh",
  "args": [
    "-c",
    "npx -y @larksuiteoapi/lark-mcp mcp -a $LARK_APP_ID -s $LARK_APP_SECRET --domain https://open.larksuite.com --oauth --token-mode user_access_token"
  ]
}

然后在 ~/.zshrc 或 ~/.bashrc 中设置：

export LARK_APP_ID="cli_xxxxx"
export LARK_APP_SECRET="your_secret_here"

---

可用的 MCP 工具

配置成功后，Claude Code 可以使用以下 Lark API：

工具	功能
bitable_v1_app_create	创建 Bitable 应用
bitable_v1_appTable_create	创建表格（含字段定义）
bitable_v1_appTable_list	列出所有表格
bitable_v1_appTableField_list	获取表格字段
bitable_v1_appTableRecord_search	搜索/读取记录
bitable_v1_appTableRecord_create	创建记录
bitable_v1_appTableRecord_update	更新记录
wiki_v2_space_getNode	获取 Wiki 节点信息
wiki_v1_node_search	搜索 Wiki
docx_v1_document_rawContent	读取文档内容
drive_v1_permissionMember_create	管理文档权限
im_v1_chat_list	列出群聊
im_v1_chatMembers_get	获取群成员

---

示例：创建 Bitable 并填充数据

# 1. 创建 Bitable 应用
bitable_v1_app_create(
    folder_token="Kf6UfA2CdlEgudd8DPqjdxxRphg",
    name="Feature Tracker"
)
# 返回: app_token = "KE5Kbp9DYaLhvTsRkyXj5Dh4pkc"

# 2. 创建带字段的表格
bitable_v1_appTable_create(
    app_token="KE5Kbp9DYaLhvTsRkyXj5Dh4pkc",
    table={
        "name": "Features",
        "fields": [
            {"field_name": "Name", "type": 1},           # 文本
            {"field_name": "Status", "type": 3, ...},    # 单选
            {"field_name": "Assignee", "type": 11},      # 人员
            {"field_name": "Progress", "type": 2},       # 数字/进度
            {"field_name": "Due Date", "type": 5},       # 日期
        ]
    }
)

# 3. 添加记录
bitable_v1_appTableRecord_create(
    app_token="...",
    table_id="...",
    fields={
        "Name": "My Feature",
        "Status": "doing",
        "Progress": 0.8  # 80%
    }
)

---

参考链接

• lark-openapi-mcp GitHub 仓库
• @larksuiteoapi/lark-mcp npm
• Lark Developer 文档
• Lark Developer Console
• Bitable 字段类型参考