概述

通过飞书官方提供的 MCP 工具 @larksuiteoapi/lark-mcp，可以让 Claude Code 直接读取和操作飞书文档、多维表格、消息等内容。

一、前置准备

1. 创建飞书应用

1. 打开 飞书开放平台，登录后点击「创建企业自建应用」
2. 填写应用名称和描述，创建完成后进入应用详情页
3. 在「凭证与基础信息」页面获取：
4. App ID（如 cli_xxxx****xxxx）
5. App Secret（如 xxxx****xxxx）

2. 配置应用权限

在飞书开放平台的应用管理页面，添加以下权限（根据需要选择）：

添加权限后，需要发布应用版本并由管理员审批通过。

3. 确保已安装 Node.js

node -v   # 需要 Node.js 环境
npm -v    # 或 npx 可用即可

二、在 Claude Code 中配置 Lark MCP

方法：使用 claude mcp add 命令

在终端中执行以下命令（将 App ID 和 App Secret 替换为你自己的）：

claude mcp add lark-mcp \
  --scope user \
  -- npx -y @larksuiteoapi/lark-mcp mcp \
  -a <你的AppID> \
  -s <你的AppSecret> \
  -p 3001 \
  --oauth \
  --token-mode user_access_token

参数说明：

重要：必须使用 --scope user（全局配置）

如果不指定 --scope user，配置默认可能保存为项目级别，只在当前目录下生效。这会导致在 VS Code 或其他目录中打开 Claude Code 时无法使用飞书工具。

• --scope user（全局）：保存在 ~/.claude.json 顶层 mcpServers 中，终端、VS Code、任何项目目录都生效
• --scope project（项目级）：保存在 ~/.claude.json 的 projects.<目录>.mcpServers 中，仅在该目录下生效

如果已经误装为项目级别，可以手动编辑 ~/.claude.json，将 lark-mcp 的配置从 projects.<目录>.mcpServers 移到顶层的 mcpServers 字段中，然后重启 Claude Code。

配置存储位置

配置会保存在 ~/.claude.json 文件顶层的 mcpServers 字段中：

{
  "mcpServers": {
    "lark-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@larksuiteoapi/lark-mcp",
        "mcp",
        "-a", "cli_xxxx****xxxx",
        "-s", "xxxx****xxxx",
        "-p", "3001",
        "--oauth",
        "--token-mode", "user_access_token"
      ],
      "env": {}
    }
  }
}

三、首次登录认证

配置完成后，首次使用时需要进行 OAuth 登录：

1. 启动 Claude Code（在配置了 lark-mcp 的目录下）
2. 当 Claude Code 调用飞书相关工具时，会自动弹出浏览器要求飞书登录授权
3. 登录授权后，token 会缓存在本地，后续使用无需重复登录

检查登录状态

npx @larksuiteoapi/lark-mcp whoami

会显示当前的登录会话信息，包括 token 是否过期。

手动登录（如果 token 过期）

npx @larksuiteoapi/lark-mcp login -a <AppID> -s <AppSecret> -p 3001

登出

npx @larksuiteoapi/lark-mcp logout -a <AppID>

四、日常使用

新开 Claude Code session 后需要做什么？

通常不需要任何额外操作。 只要满足以下条件：

1. MCP 配置已保存（一次配置，永久生效）
2. OAuth token 未过期（token 有较长有效期，且配置了 --oauth 会自动刷新）

直接在 Claude Code 中对话即可，例如：
– “帮我读取这个飞书文档 https://xxx.feishu.cn/docx/xxxxx”
– “查看飞书多维表格的内容”
– “搜索飞书文档”

如果 token 已过期，Claude Code 会自动触发重新登录流程。

可用的飞书工具

配置完成后，Claude Code 中会自动加载以下工具（根据应用权限）：

从飞书链接中提取 document_id

飞书文档链接格式：

https://xxx.feishu.cn/docx/<document_id>

例如：

https://xxxxx.feishu.cn/docx/Ir4rdQMDQotGbnx9mRkcni79nrb
                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                  这部分就是 document_id

五、常见问题

Q: 在 VS Code 中的 Claude Code 无法访问飞书？

最常见的原因是配置作用域不对。MCP 有两种作用域：

• --scope user（全局）：配置保存在 ~/.claude.json 顶层的 mcpServers 中，任何目录、任何环境（终端/VS Code）都生效
• --scope project（项目级）：配置保存在 ~/.claude.json 的 projects.<目录路径>.mcpServers 中，只在该目录下生效

如果你在终端的 ~ 目录下用 claude mcp add 添加，默认可能会添加为项目级配置，导致 VS Code 中打开其他项目时找不到 lark-mcp。

解决方法： 确保使用 --scope user 添加，或者手动编辑 ~/.claude.json，将 lark-mcp 配置从 projects./Users/xxx.mcpServers 移到顶层的 mcpServers 中。修改后重启 Claude Code 即可。

Q: 切换目录后飞书工具不可用？

同上，使用 --scope user 配置即可全局生效。

Q: Token 过期了怎么办？

配置了 --oauth 参数后，token 过期时会自动引导重新登录。也可以手动执行：

npx @larksuiteoapi/lark-mcp login -a <AppID> -s <AppSecret> -p 3001

Q: 如何查看或删除 MCP 配置？

# 查看所有 MCP 服务
claude mcp list

# 删除 lark-mcp
claude mcp remove lark-mcp

Q: 端口冲突怎么办？

将 -p 3001 改为其他未占用的端口即可。

六、参考资料

• 工具包：@larksuiteoapi/lark-mcp（npm 包）
• 飞书开放平台：https://open.feishu.cn
• Claude Code MCP 文档：claude mcp --help