mthoutai

  博客园  :: 首页  :: 新随笔  :: 联系 :: 订阅 订阅  :: 管理

深入解析：Claude Code集成飞书 MCP 实施方案

Claude Code集成飞书 MCP 实施方案

作者: shouzhi
创建时间: 2026-01-16
版本: v1.1
更新记录: 增加 MCP 服务器安装部署章节

目录

  1. 前置准备清单
  2. 飞书开放平台应用配置
  3. 官方飞书 MCP 安装部署
  4. 自定义飞书 MCP 开发部署
  5. Claude Code MCP 配置
  6. 用户身份认证
  7. 常用使用方式
  8. 问题排查记录
  9. 验证测试
  10. 配置文件完整示例
  11. 注意事项
  12. 参考链接

一、前置准备清单

在开始实施前，请确保已准备以下内容：

序号准备项说明必须
1Node.js 环境版本 >= 20.0.0✅
2Claude Code CLI版本 >= 2.1.x✅
3飞书开放平台应用获取 App ID 和 App Secret✅
4飞书应用权限配置配置云文档相关权限✅
5OAuth 重定向 URI用于用户身份认证可选
6Git（自定义 MCP）用于克隆项目可选

环境变量声明

以下变量将在后续步骤中使用，请提前准备：

# 飞书应用凭证（从飞书开放平台获取）
FEISHU_APP_ID="cli_xxxxxxxxx"
FEISHU_APP_SECRET="xxxxxxxxxxxxxxxx"
# Node.js 路径（根据实际安装位置调整）
NODE_PATH="/Users/shouzhi/.nvm/versions/node/v22.17.0/bin"
# 自定义 MCP 项目路径（可选）
FEISHU_MCP_PROJECT="/Users/shouzhi/nvxclouds/project/feishu-mcp"

二、飞书开放平台应用配置

2.1 创建应用

  1. 登录 飞书开放平台
  2. 点击「创建企业自建应用」
  3. 填写应用名称和描述
  4. 获取 App ID 和 App Secret

2.2 配置应用权限

在应用的「权限管理」中开通以下权限：

云文档相关权限：

权限标识权限名称说明
docs:doc云文档查看、评论、编辑和管理云文档
docs:doc:create创建云文档创建新的云文档
drive:drive云空间查看、编辑和管理云空间文件
wiki:wiki知识库查看、编辑和管理知识库
bitable:bitable多维表格查看、编辑多维表格
im:message消息发送消息（可选）

2.3 配置 OAuth 重定向 URI（用户身份认证）

如需使用用户身份创建文档，需配置重定向 URI：

  1. 进入应用的「安全设置」
  2. 在「重定向 URL」中添加：
    http://localhost:3000/callback
  3. 保存配置

⚠️ 注意：未配置此项会导致 OAuth 登录失败，报错 Error code: 20029 redirect_uri request is invalid

2.4 发布应用

  1. 进入「版本管理与发布」
  2. 创建版本并提交审核
  3. 审核通过后发布应用

三、官方飞书 MCP 安装部署

官方飞书 MCP 是由飞书官方提供的 NPM 包 @larksuiteoapi/lark-mcp，功能全面，覆盖云文档、多维表格、消息等多个模块。

3.1 架构说明

┌─────────────────┐     ┌──────────────────────────┐     ┌─────────────────┐
│   Claude Code   │────▶│  @larksuiteoapi/lark-mcp │────▶│  飞书开放平台    │
│   (MCP Client)  │◀────│      (MCP Server)        │◀────│   Open API      │
└─────────────────┘     └──────────────────────────┘     └─────────────────┘

3.2 安装方式

官方 MCP 无需手动安装，通过 npx 自动下载运行：

# 验证包是否可用
npx -y @larksuiteoapi/lark-mcp --help

输出示例：

Usage: lark-mcp [options] [command]
Feishu/Lark MCP Tool
Options:
  -V, --version    output the version number
  -h, --help       display help for command
Commands:
  whoami           Print All User Sessions
  login [options]  Login using OAuth and get user access token
  logout [options] Logout and clear stored user access token
  mcp [options]    Start Feishu/Lark MCP Service
  help [command]   display help for command

3.3 可用命令

命令说明示例
mcp启动 MCP 服务器npx -y @larksuiteoapi/lark-mcp mcp -a <APP_ID> -s <APP_SECRET>
loginOAuth 用户登录npx -y @larksuiteoapi/lark-mcp login -a <APP_ID> -s <APP_SECRET>
logout登出用户npx -y @larksuiteoapi/lark-mcp logout
whoami查看当前登录用户npx -y @larksuiteoapi/lark-mcp whoami

3.4 MCP 服务器启动参数

npx -y @larksuiteoapi/lark-mcp mcp [options]
参数说明必须
-a, --app-id <id>飞书应用 App ID✅
-s, --app-secret <secret>飞书应用 App Secret✅
-t, --tools <tools>启用的工具列表（逗号分隔）否

3.5 测试 MCP 协议

# 测试 MCP 协议初始化
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | npx -y @larksuiteoapi/lark-mcp mcp -a $FEISHU_APP_ID -s $FEISHU_APP_SECRET

预期输出：

{
"result": {
"protocolVersion": "2024-11-05",
"capabilities": {"tools": {"listChanged": true}},
"serverInfo": {"id": "lark-mcp-server", "name": "Feishu/Lark MCP Server", "version": "0.5.1"}
},
"jsonrpc": "2.0",
"id": 1
}

3.6 提供的工具列表

官方 MCP 提供以下工具（部分列表）：

模块工具名称功能
云文档docx_builtin_import导入 Markdown 创建云文档
云文档docx_builtin_search搜索云文档
云文档docx_v1_document_rawContent获取文档纯文本内容
知识库wiki_v1_node_search搜索知识库
知识库wiki_v2_space_getNode获取知识库节点信息
多维表格bitable_v1_app_create创建多维表格
多维表格bitable_v1_appTable_create创建数据表
多维表格bitable_v1_appTableRecord_create创建记录
多维表格bitable_v1_appTableRecord_search搜索记录
消息im_v1_message_create发送消息
消息im_v1_chat_create创建群聊
权限drive_v1_permissionMember_create添加协作者权限

四、自定义飞书 MCP 开发部署

自定义飞书 MCP 是对官方 MCP 的补充，主要提供文档块级别的编辑能力，如创建标题块、文本块、代码块等。

4.1 架构说明

┌─────────────────┐     ┌──────────────────────────┐     ┌─────────────────┐
│   Claude Code   │────▶│     feishu-mcp           │────▶│  飞书开放平台    │
│   (MCP Client)  │◀────│  (自定义 MCP Server)      │◀────│   Open API      │
└─────────────────┘     └──────────────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │  功能模块         │
                        ├──────────────────┤
                        │ • 文档管理        │
                        │ • 块操作（CRUD）  │
                        │ • 认证管理        │
                        └──────────────────┘

4.2 项目结构

feishu-mcp/
├── src/
│   ├── index.ts          # 主入口，MCP 服务器定义
│   ├── auth/
│   │   └── token.ts      # 飞书 Token 管理
│   ├── tools/
│   │   └── document.ts   # 文档操作工具定义
│   └── types/
│       └── index.ts      # TypeScript 类型定义
├── dist/                 # 编译输出目录
├── package.json
├── tsconfig.json
└── README.md

4.3 安装部署步骤

步骤一：克隆或创建项目
# 如果是现有项目
cd /Users/shouzhi/nvxclouds/project/feishu-mcp
# 如果是新建项目
mkdir -p /path/to/feishu-mcp && cd /path/to/feishu-mcp
步骤二：初始化项目（新建时）
# 初始化 npm 项目
npm init -y
# 安装依赖
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node
步骤三：安装依赖
npm install

package.json 依赖说明：

{
"name": "@nvxclouds/feishu-mcp",
"version": "1.0.0",
"type": "module",
"main": "dist/index.js",
"scripts": {
"build": "tsc",
"dev": "tsc --watch",
"start": "node dist/index.js",
"inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
},
"dependencies": {
"@modelcontextprotocol/sdk": "^1.12.0",
"zod": "^3.24.0"
},
"devDependencies": {
"@types/node": "^22.10.5",
"typescript": "^5.7.3"
},
"engines": {
"node": ">=20.0.0"
}
}
步骤四：编译项目
npm run build

输出示例：

> tsc
# 无错误输出表示编译成功
步骤五：验证编译结果
ls -la dist/

预期输出：

total 56
drwxr-xr-x  9 shouzhi  staff    288 Jan 16 15:39 .
drwxr-xr-x  9 shouzhi  staff    288 Jan 16 15:39 ..
drwxr-xr-x  3 shouzhi  staff     96 Jan 16 15:39 auth
-rw-r--r--  1 shouzhi  staff  12345 Jan 16 15:39 index.js
drwxr-xr-x  3 shouzhi  staff     96 Jan 16 15:39 tools
drwxr-xr-x  3 shouzhi  staff     96 Jan 16 15:39 types

4.4 测试 MCP 服务器

方式一：直接运行
node dist/index.js -a $FEISHU_APP_ID -s $FEISHU_APP_SECRET

预期输出：

飞书 MCP 服务器已启动
方式二：使用 MCP Inspector 调试
npm run inspect
# 或
npx @modelcontextprotocol/inspector node dist/index.js -a $FEISHU_APP_ID -s $FEISHU_APP_SECRET

会打开浏览器，提供可视化的工具测试界面。

方式三：测试 MCP 协议
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node dist/index.js -a $FEISHU_APP_ID -s $FEISHU_APP_SECRET 2>/dev/null

预期输出：

{
"result": {
"protocolVersion": "2024-11-05",
"capabilities": {"tools": {}},
"serverInfo": {"name": "feishu-mcp", "version": "1.0.0"}
},
"jsonrpc": "2.0",
"id": 1
}

4.5 提供的工具列表

工具名称功能描述参数
feishu-create-document创建新云文档title, folder_id(可选)
feishu-get-document获取文档基本信息document_id
feishu-get-raw-content获取文档纯文本内容document_id
feishu-get-blocks获取文档所有块信息document_id, page_token(可选)
feishu-create-text-block创建文本块document_id, parent_block_id, content, index(可选)
feishu-create-heading-block创建标题块document_id, parent_block_id, content, level(1-9)
feishu-create-code-block创建代码块document_id, parent_block_id, content, language
feishu-update-block-content更新块内容document_id, block_id, content

4.6 开发扩展（可选）

如需添加新工具，参考以下代码结构：

// src/tools/document.ts
import { z } from 'zod';
// 定义工具参数 Schema
export const createDocumentSchema = z.object({
title: z.string().describe('文档标题'),
folder_id: z.string().optional().describe('目标文件夹 ID')
});
// 在 index.ts 中注册工具
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
{
name: 'feishu-create-document',
description: '创建新的飞书云文档',
inputSchema: zodToJsonSchema(createDocumentSchema)
}
]
}));

五、Claude Code MCP 配置

5.1 配置文件位置

⚠️ 重要：Claude Code 的全局 MCP 配置位置是 ~/.claude.json，而不是 ~/.claude/mcp.json。

文件用途
~/.claude.json全局配置文件，包含 mcpServers 字段
~/.claude/settings.json设置文件，包含插件、代理等配置
~/.claude/mcp.json❌ 不是 MCP 服务器的配置位置

5.2 MCP 服务器配置

编辑 ~/.claude.json 文件，在 mcpServers 字段中添加飞书 MCP：

{
"mcpServers": {
"feishu": {
"type": "stdio",
"command": "/Users/shouzhi/.nvm/versions/node/v22.17.0/bin/npx",
"args": [
"-y",
"@larksuiteoapi/lark-mcp",
"mcp",
"-a", "<YOUR_APP_ID>",
  "-s", "<YOUR_APP_SECRET>"
    ],
    "env": {}
    },
    "feishu-edit": {
    "type": "stdio",
    "command": "/Users/shouzhi/.nvm/versions/node/v22.17.0/bin/node",
    "args": [
    "/Users/shouzhi/nvxclouds/project/feishu-mcp/dist/index.js",
    "-a", "<YOUR_APP_ID>",
      "-s", "<YOUR_APP_SECRET>"
        ],
        "env": {}
        }
        }
        }

5.3 配置要点

配置项说明建议
type传输类型必须为 "stdio"
command执行命令使用绝对路径，避免 PATH 问题
args命令参数包含 MCP 启动参数和飞书凭证
env环境变量可为空对象 {}

5.4 获取 Node.js 绝对路径

# 获取 node 路径
which node
# 输出: /Users/shouzhi/.nvm/versions/node/v22.17.0/bin/node
# 获取 npx 路径
which npx
# 输出: /Users/shouzhi/.nvm/versions/node/v22.17.0/bin/npx

5.5 验证配置

重启 Claude Code 后，输入 /mcp 查看 MCP 状态：

Manage MCP servers
6 servers
User MCPs (/Users/shouzhi/.claude.json)
> feishu · ✓ connected
> feishu-edit · ✓ connected
  notion · ✓ connected
  canva-dev · ✓ connected

六、用户身份认证

6.1 应用身份 vs 用户身份

身份类型Token 类型文档所有者适用场景
应用身份tenant_access_token应用自动化任务、后台脚本
用户身份user_access_token用户文档出现在个人空间

6.2 用户登录

npx -y @larksuiteoapi/lark-mcp login -a <APP_ID> -s <APP_SECRET>

执行后会打开浏览器进行 OAuth 授权：

  1. 浏览器自动打开飞书授权页面
  2. 用户点击「授权」
  3. 授权成功后令牌保存在本地

6.3 查看当前用户

npx -y @larksuiteoapi/lark-mcp whoami

6.4 登出用户

npx -y @larksuiteoapi/lark-mcp logout

6.5 重新加载令牌

用户授权后，需要重启 Claude Code 才能加载新的用户令牌：

# 退出当前会话
/exit
# 重新启动
claude

七、常用使用方式

7.1 工具调用方式

Claude Code 会根据用户意图自动选择和调用工具，无需显式指定工具名称。

方式说明推荐
自然语言用普通话描述需求，Claude 自动选择工具✅ 推荐
显式调用直接说工具名称通常不需要

7.2 使用示例

创建文档
请帮我在飞书创建一个项目周报文档，包含本周完成的工作和下周计划

Claude 会自动：

  1. 识别意图：创建飞书文档
  2. 选择工具：mcp__feishu__docx_builtin_import
  3. 生成内容并调用工具
  4. 返回文档链接
搜索文档
搜索飞书里关于 API 部署的文档
读取文档
帮我读一下这个飞书文档的内容：https://xxx.feishu.cn/docx/xxxxx
发送消息
给飞书群发一条消息通知大家下午3点开会
操作多维表格
在飞书多维表格里新增一条项目记录，项目名称是"MCP集成"，状态是"进行中"

7.3 工作流程图

┌──────────────────┐
│  用户输入需求     │
│ "创建Redis文档"  │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  Claude 分析意图  │
│ 识别：创建飞书文档│
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  选择合适的工具   │
│ docx_builtin_import│
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  生成工具参数     │
│ {file_name, markdown}│
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  调用 MCP 工具    │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  返回结果给用户   │
│ 文档链接: https://│
└──────────────────┘

7.4 身份选择指南

场景推荐身份参数/操作
文档需要出现在个人空间用户身份useUAT: true
自动化脚本/后台任务应用身份useUAT: false
创建到指定文件夹应用身份指定 folder_token
读取公开文档应用身份useUAT: false

八、问题排查记录

8.1 问题一：MCP 服务器未加载

现象：配置了 MCP 服务器，但 /mcp 命令看不到飞书 MCP。

排查过程：

  1. 检查 ~/.claude/mcp.json - 配置存在但未生效
  2. 检查 ~/.claude/settings.json 的 enabledMcpjsonServers - 已启用
  3. 测试 MCP 服务器协议 - 服务器能正常响应
  4. 检查其他插件的 MCP 配置格式 - 发现配置位置不同

根因：Claude Code 读取的 MCP 配置不在 ~/.claude/mcp.json，而是在 ~/.claude.json 的 mcpServers 字段中。

解决方案：将飞书 MCP 配置添加到 ~/.claude.json 的 mcpServers 字段。

8.2 问题二：OAuth 重定向 URI 无效

现象：执行登录命令时，浏览器报错：

Error code: 20029 redirect_uri request is invalid

根因：飞书应用未配置 OAuth 重定向 URI。

解决方案：在飞书开放平台的应用安全设置中添加重定向 URL：

http://localhost:3000/callback

8.3 问题三：文档不在个人云文档中

现象：通过 MCP 创建的文档可以通过链接访问，但在个人云文档中搜不到。

根因：使用应用身份（tenant_access_token）创建的文档，所有者是应用而非用户。

解决方案：

  1. 方案一：使用用户身份创建

    npx -y @larksuiteoapi/lark-mcp login -a <APP_ID> -s <APP_SECRET>
  # 然后重启 Claude Code

  2. 方案二：指定文件夹 token 创建到用户的指定文件夹

8.4 问题四：用户令牌过期

现象：调用工具时报错 Current user_access_token is invalid or expired

解决方案：

# 重新登录
npx -y @larksuiteoapi/lark-mcp login -a <APP_ID> -s <APP_SECRET>
  # 重启 Claude Code

九、验证测试

9.1 测试步骤

  1. 启动 Claude Code
  2. 输入 /mcp 查看 MCP 服务器状态
  3. 确认 feishu 和 feishu-edit 显示为 connected
  4. 测试创建文档功能

9.2 测试用例

测试项命令/操作预期结果
MCP 连接/mcp显示 connected
应用身份创建文档“创建测试文档”返回文档链接
用户身份创建文档登录后创建文档出现在个人空间
创建标题块创建带标题的文档标题正常显示
创建文本块添加文本内容文本正常显示

9.3 测试结果

测试项结果备注
MCP 连接✅ 成功-
应用身份创建文档✅ 成功https://bytedance.larkoffice.com/docx/JonNdT404oHfLaxfzsfcHhPwnMB
用户身份创建文档✅ 成功https://qve2nhytr9.feishu.cn/docx/CI5BdAXGdoRzRcxWGuscZinenBe
创建标题块✅ 成功-
创建文本块✅ 成功-
创建代码块❌ 失败参数校验问题，待修复

十、配置文件完整示例

~/.claude.json（关键部分）

{
"mcpServers": {
"notion": {
"type": "http",
"url": "https://mcp.notion.com/mcp"
},
"canva-dev": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@canva/cli@latest", "mcp"],
"env": {}
},
"feishu": {
"type": "stdio",
"command": "/Users/shouzhi/.nvm/versions/node/v22.17.0/bin/npx",
"args": [
"-y",
"@larksuiteoapi/lark-mcp",
"mcp",
"-a", "cli_a9c34f2049",
"-s", "9CLp6eI5uLdGlNiBPtNKWg4IsJ"
],
"env": {}
},
"feishu-edit": {
"type": "stdio",
"command": "/Users/shouzhi/.nvm/versions/node/v22.17.0/bin/node",
"args": [
"/Users/shouzhi/nvxclouds/project/feishu-mcp/dist/index.js",
"-a", "cli_a9c3495bc6",
"-s", "9CLp6eI5uLdGlNiBPtNKWg4IsJ"
],
"env": {}
}
}
}

十一、注意事项

安全相关

  1. App Secret 保护：App Secret 是敏感信息，请勿提交到公开仓库
  2. 配置文件权限：确保 ~/.claude.json 文件权限为 600

使用相关

  1. 令牌刷新：用户令牌有效期有限，过期后需重新登录
  2. 重启生效：修改 MCP 配置或用户授权后，需重启 Claude Code
  3. 权限检查：确保飞书应用已开通所需的 API 权限
  4. 网络代理：如使用代理，确保飞书 API 域名（open.feishu.cn）可访问

开发相关

  1. Node.js 版本：确保 Node.js 版本 >= 20.0.0
  2. 路径问题：MCP 配置中使用绝对路径避免 PATH 环境变量问题
  3. 编译检查：修改自定义 MCP 代码后需重新执行 npm run build

十二、参考链接

资源链接
飞书开放平台https://open.feishu.cn/
飞书 MCP NPM 包https://www.npmjs.com/package/@larksuiteoapi/lark-mcp
Claude Code MCP 文档https://code.claude.com/docs/en/mcp
飞书云文档 APIhttps://open.feishu.cn/document/server-docs/docs/docs-overview
MCP 协议规范https://modelcontextprotocol.io/
MCP SDKhttps://www.npmjs.com/package/@modelcontextprotocol/sdk
posted on 2026-02-14 20:35  mthoutai  阅读(1756)  评论(0)    收藏  举报