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. 参考链接

一、前置准备清单

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

序号 准备项 说明 必须
1 Node.js 环境 版本 >= 20.0.0 ✅
2 Claude Code CLI 版本 >= 2.1.x ✅
3 飞书开放平台应用 获取 App ID 和 App Secret ✅
4 飞书应用权限配置 配置云文档相关权限 ✅
5 OAuth 重定向 URI 用于用户身份认证 可选
6 Git（自定义 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>
login OAuth 用户登录 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
飞书云文档 API https://open.feishu.cn/document/server-docs/docs/docs-overview
MCP 协议规范 https://modelcontextprotocol.io/
MCP SDK https://www.npmjs.com/package/@modelcontextprotocol/sdk
Logo
2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

cover

GitHub 热榜项目-日榜精选（2026-02-02）| AI智能体、终端工具、视频生成等 | openclaw、99、Maestro等

avatar 2048 AI社区
cover

基于YOLO+DeepSeek+Pytorch+SpringBoot+Flask+Vue血液细胞检测专家系统

avatar 2048 AI社区
cover

毕业设计：YOLO猪只行为智能检测系统（源码）

avatar 2048 AI社区