@akaknele/feishu-wiki-mcp

v1.3.1

Published

13 days ago

Feishu Wiki MCP Server - 飞书知识库管理工具

0High
0Medium
0Low

akaken

mcp feishu lark wiki bitable tooling

飞书 MCP 使用指南（feishu-wiki-mcp）

本项目是面向 MCP 客户端的飞书服务网关，运行时通过飞书开放平台 API 提供标准化工具调用。

运行时：Node.js >= 20 + stdio transport（@modelcontextprotocol/sdk）
入口：build/index.js
当前版本：1.3.0
包名：@akaknele/feishu-wiki-mcp
当前可用 Tool：36 个

一、部署与启动方式

1. 开发构建与本地运行

npm install
npm run build
npm start -- --app-id <APP_ID> --app-secret <APP_SECRET>

2. OAuth 模式（用于用户授权）

适用于需要用户级权限（user token）的场景：

npm start -- --app-id <APP_ID> --app-secret <APP_SECRET> --oauth --port 3001

2b. 预置 Token 模式（无浏览器，适合第三方 MCP 客户端）

当第三方应用（Claude Desktop、Cursor 等）安装 MCP 无法弹出浏览器时，可提前获取 user token 后通过参数或环境变量传入，完全跳过 OAuth 授权流程：

# 命令行参数
feishu-wiki-mcp --app-id <APP_ID> --app-secret <APP_SECRET> \
  --user-token <USER_ACCESS_TOKEN> \
  --refresh-token <REFRESH_TOKEN>

# 或环境变量（推荐）
FEISHU_APP_ID=cli_xxx \
FEISHU_APP_SECRET=secret_xxx \
FEISHU_USER_TOKEN=u-xxx \
FEISHU_REFRESH_TOKEN=ur-xxx \
feishu-wiki-mcp

MCP 客户端配置示例：

{
  "mcpServers": {
    "feishu-wiki-mcp": {
      "command": "feishu-wiki-mcp",
      "args": ["--app-id", "<APP_ID>", "--app-secret", "<APP_SECRET>"],
      "env": {
        "FEISHU_USER_TOKEN": "<USER_ACCESS_TOKEN>",
        "FEISHU_REFRESH_TOKEN": "<REFRESH_TOKEN>"
      }
    }
  }
}

token 过期后会自动用 refresh_token 刷新；refresh_token 也过期则报错，需重新获取。

2c. 如何获取 User Token

预置模式需要提前拿到 user_access_token 和 refresh_token，有以下三种方式：

方式一：运行一次 `--oauth`，从缓存文件提取（推荐）

在有浏览器的机器上完成一次授权：

feishu-wiki-mcp --app-id cli_xxx --app-secret xxx --oauth --port 3001

授权成功后读取缓存文件：

cat ~/.feishu-wiki-mcp-token.json

输出示例：

{
  "access_token": "u-xxx...",
  "refresh_token": "ur-xxx...",
  "expires_at": 1234567890000,
  "refresh_expires_at": 9876543210000
}

将 access_token 和 refresh_token 填入环境变量即可。refresh_token 有效期约 30 天，MCP 会自动续期 access_token，正常使用无感知。

方式二：飞书开放平台 API 调试台（无需写代码）

打开 open.feishu.cn → 进入你的应用
左侧菜单选择 "开发工具 → API 调试台"
右上角鉴权方式选择 "用户身份（user_access_token）"，点击授权登录
授权完成后，调试台会自动填入 token，复制即可

方式三：手动 OAuth 换 token（Shell 脚本）

适合自动化脚本场景，需要一个可访问的回调地址（本地 localhost 即可）：

# 替换为你的 App ID / Secret
APP_ID="cli_xxx"
APP_SECRET="xxx"
PORT=3001

# Step 1：用浏览器打开授权 URL，完成后从地址栏取 code 参数
SCOPES="wiki:wiki docx:document drive:drive bitable:bitable im:message contact:user.id:readonly"
echo "请用浏览器访问以下地址完成授权："
echo "https://open.feishu.cn/open-apis/authen/v1/index?app_id=${APP_ID}&redirect_uri=http%3A%2F%2Flocalhost%3A${PORT}%2Fcallback&scope=$(python3 -c "import urllib.parse; print(urllib.parse.quote('${SCOPES}'))")"
echo ""
read -p "粘贴回调 URL 中的 code 参数值: " CODE

# Step 2：获取 app_access_token
APP_TOKEN=$(curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal" \
  -H "Content-Type: application/json" \
  -d "{\"app_id\":\"${APP_ID}\",\"app_secret\":\"${APP_SECRET}\"}" | jq -r .app_access_token)

# Step 3：用 code 换 user_access_token + refresh_token
curl -s -X POST "https://open.feishu.cn/open-apis/authen/v1/oidc/access_token" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${APP_TOKEN}" \
  -d "{\"grant_type\":\"authorization_code\",\"code\":\"${CODE}\"}" | jq '{access_token: .data.access_token, refresh_token: .data.refresh_token}'

运行后输出的 access_token 和 refresh_token 即可填入环境变量。

Token 有效期说明

| Token | 有效期 | 过期行为 | |-------|--------|---------| | user_access_token | ~2 小时 | MCP 自动用 refresh_token 续期 | | refresh_token | ~30 天 | 需重新走上述任一方式获取 |

3. 安装后直接运行

npm install -g @akaknele/[email protected]
feishu-wiki-mcp --app-id <APP_ID> --app-secret <APP_SECRET>

或使用 npx：

npx @akaknele/[email protected] --app-id <APP_ID> --app-secret <APP_SECRET>

4. MCP 客户端接入（示例）

{
  "mcpServers": {
    "feishu-wiki-mcp": {
      "command": "feishu-wiki-mcp",
      "args": ["--app-id", "<APP_ID>", "--app-secret", "<APP_SECRET>"]
    }
  }
}

OAuth 模式示例：

{
  "mcpServers": {
    "feishu-wiki-mcp": {
      "command": "feishu-wiki-mcp",
      "args": ["--app-id", "<APP_ID>", "--app-secret", "<APP_SECRET>", "--oauth", "--port", "3001"]
    }
  }
}

二、外网网络（OAuth）要求

若在企业内网/防火墙下运行，需要放行：

https://open.feishu.cn
https://openapi.*.feishu.cn（飞书 API 域名）

OAuth 回调地址默认为：

http://localhost:3001/callback

因此对应机器的 3001 端口需要可访问（对本机浏览器即可），并且回调 URL 能回传到该本机实例。

三、核心流程

启动服务并通过参数选择 tenant 模式或 OAuth 模式
MCP 客户端请求对应 tool
服务器内部自动获取并刷新 token（~/.feishu-wiki-mcp-token.json）
使用 token 调用飞书接口并返回结构化 JSON

四、工具清单（36）

工具清单质量说明

每个工具都以 MCP tool schema 的实际参数定义为准，返回值默认为飞书 API 的 JSON 响应文本。

知识库（Wiki）

| 工具 | 用途 | 必填参数 | 可选参数 | | --- | --- | --- | --- | | wiki_list_spaces | 列出当前用户可见知识库 | 无 | page_size（1-50）, page_token | | wiki_get_space | 获取知识库详情 | space_id | 无 | | wiki_list_nodes | 列出知识库子节点（默认顶层） | space_id | parent_node_token, page_size（1-50）, page_token | | wiki_get_node | 通过 wiki token 或文档 token 获取节点 | token | obj_type（doc/docx/sheet/mindnote/bitable/file/slides/wiki） | | wiki_create_node | 创建知识库节点（文档/表格等） | space_id, obj_type | parent_node_token, node_type（origin/shortcut, 默认 origin）, title | | wiki_move_node | 在知识库内移动节点 | space_id, node_token | target_parent_token, target_space_id | | wiki_move_docs_to_wiki | 将云空间文档移动进知识库 | space_id, obj_type, obj_token | parent_wiki_token | | wiki_update_title | 更新节点标题 | space_id, node_token, title | 无 | | wiki_copy_node | 复制节点（可跨库） | space_id, node_token | target_parent_token, target_space_id, title | | wiki_search | 搜索知识库节点 | query | space_id, page_size, page_token | | wiki_create_node_with_markdown | 🆕 一步创建带 Markdown 内容的 wiki 文档（上传→转换→移入知识库） | space_id, markdown | title（<=27 字符）, parent_node_token |

文档（Docx）

| 工具 | 用途 | 必填参数 | 可选参数 | | --- | --- | --- | --- | | doc_get_raw_content | 获取文档纯文本内容 | document_id | 无 | | doc_search | 搜索云文档 | search_key | count（0-50）, offset, owner_ids, docs_types | | doc_import | 导入 Markdown 创建飞书文档（自动上传 → 转换 docx）。🆕 v1.3: 可选传入 space_id 直接写入知识库 | markdown | file_name（<=27 字符）, folder_token, space_id（传入后自动移入知识库）, parent_wiki_token | | doc_list_blocks | 列出文档所有块 | document_id | page_size（1-500）, page_token, document_revision_id | | doc_get_block | 获取指定块详情 | document_id, block_id | document_revision_id | | doc_create_blocks | 在指定父块下插入子块。🆕 v1.3: 补全所有 block_type 文档 + 客户端参数校验 | document_id, block_id, children | index（插入位置，默认追加） | | doc_update_block | 更新指定块内容（PATCH） | document_id, block_id, update | 无 | | doc_delete_blocks | 删除父块下指定区间的子块 | document_id, block_id, start_index, end_index | 无 |

多维表格（Bitable）

| 工具 | 用途 | 必填参数 | 可选参数 | | --- | --- | --- | --- | | bitable_create_app | 创建多维表格应用 | 无 | name, folder_token | | bitable_list_tables | 列出应用内表 | app_token | page_size, page_token | | bitable_create_table | 创建数据表 | app_token, name | default_view_name, fields（字段列表） | | bitable_list_fields | 列出表字段 | app_token, table_id | page_size, page_token | | bitable_search_records | 条件筛选记录 | app_token, table_id | field_names, filter（conjunction+conditions）, sort, page_size（<=500）, page_token | | bitable_create_record | 新增记录 | app_token, table_id, fields | 无 | | bitable_update_record | 更新记录 | app_token, table_id, record_id, fields | 无 |

IM 与联系人

| 工具 | 用途 | 必填参数 | 可选参数 | | --- | --- | --- | --- | | im_send_message | 发送消息（文本/卡片等） | receive_id, receive_id_type, msg_type, content | 无 | | im_list_messages | 获取聊天历史 | container_id | container_id_type（chat/thread，默认 chat）, start_time, end_time, sort_type, page_size, page_token | | im_list_chats | 获取用户/机器人群聊列表 | 无 | page_size, page_token, sort_type | | im_create_chat | 创建群聊 | 无 | name, description, chat_type（private/public）, user_id_list, owner_id | | im_get_chat_members | 获取群成员 | chat_id | page_size, page_token | | contact_batch_get_user_id | 批量通过邮箱/手机号查用户 ID | 无 | emails（每项 string, 最多 50）, mobiles（每项 string, 最多 50） |

权限与删除

| 工具 | 用途 | 必填参数 | 可选参数 | | --- | --- | --- | --- | | drive_add_permission | 为云文档添加协作者权限 | token, type, member_id, member_type, perm | 无 | | wiki_delete_node | 将 wiki 节点移出到云空间根目录（第一步）；之后用 drive_delete_file 彻底删除（飞书无公开 wiki 删除 API） | space_id, node_token（wiki node token，非 obj_token） | 无 | | drive_upload_file | 🆕 上传文件到云空间（base64），获取 file_token 用于插入图片等 | file_name, base64 | parent_type（默认 explorer）, parent_node | | drive_delete_file | 删除云空间文件（移至回收站） | file_token, type | 无 |

说明

fields（Bitable 相关）通常使用字段名/系统键映射值；建议先用 bitable_list_fields 明确 schema 后再写入。
im_send_message 的 content 按对应 msg_type 要求传入 JSON 字符串。
doc_import：先上传 md 文件获取 file_token，再创建导入任务转换为 docx，轮询等待最多 30 秒。v1.3 新增 space_id + parent_wiki_token 参数，导入后可自动移入知识库。
wiki_create_node_with_markdown：一步到位创建带内容的 wiki 文档。内部自动完成：上传 Markdown → 转换为 docx → 移入知识库。适合 AI Agent 快速创建结构化文档。
doc_create_blocks：v1.3 新增客户端参数校验，block_type 与字段名不匹配时会返回明确错误提示（如 block_type=4 需要字段 "heading2"），避免飞书 API 返回笼统的 invalid param。支持的 block_type：2=text, 3-9=heading1-7, 11=bullet, 12=ordered, 14=code, 15=quote, 22=divider, 27=image, 31=table, 34=callout。
drive_upload_file：上传 base64 编码的文件到云空间，返回 file_token，可配合 doc_create_blocks 的 image block（block_type=27）在文档中插入图片。
wiki_delete_node：飞书无公开 wiki 删除 API。本工具将节点移出 wiki 至云空间根目录（step1），之后需通过 drive_delete_file 删除底层文件（step2）。需要 wiki node token，可从 wiki_list_nodes 返回的 node_token 字段获取。

五、安全与生产部署

最小可运行参数清单

启动参数（必备）

--app-id：飞书应用 ID（必填，可用 FEISHU_APP_ID 环境变量代替）
--app-secret：飞书应用 Secret（必填，可用 FEISHU_APP_SECRET 代替）
--oauth：启动浏览器 OAuth 授权模式（可选）
--port：OAuth 回调端口（可选，默认 3001）
--user-token：预置用户 access token，跳过浏览器授权（可选，可用 FEISHU_USER_TOKEN 代替）
--refresh-token：预置 refresh token，token 过期时自动刷新（可选，可用 FEISHU_REFRESH_TOKEN 代替）

版本与发布一致性

当前代码版本：1.3.0（package.json 中 version）
MCP 运行主文件：build/index.js
发布示例（建议保持一致）：

npm version patch                      # 或 npm version 1.0.7
npm run build                          # 确保生成 build/index.js
npm publish --access public

# 标签建议与版本一致
git tag v1.0.7
git push --tags

安全与生产环境建议

端口访问控制

OAuth 回调默认地址固定为 http://localhost:${port}/callback（当前实现不支持自定义 callback host/path）。
生产部署中建议只对内网开放 3001，并通过反向代理对外暴露时加 IP 白名单/鉴权。
避免将该端口放到公开网段；如需公网访问，建议使用 VPN 或 SSH 隧道到内网服务端。

token 文件权限

用户 token 缓存在 ~/.feishu-wiki-mcp-token.json。
建议设置严格权限：

chmod 600 ~/.feishu-wiki-mcp-token.json
chown "$USER" ~/.feishu-wiki-mcp-token.json

建议使用独立运行用户，避免多人共享 HOME 目录。
需要强制重新登录时，删除该文件可清除会话缓存。

日志脱敏

运行时禁止在 shell 中开启 set -x，避免把 APP_SECRET 打印到日志。
当前日志仅输出错误描述，不应泄露 token 明文；如你接入统一日志系统，请开启敏感字段脱敏（如 app_secret、token）。

回调地址与 HTTPS 要求

本地开发/单机场景：http://localhost:<port>/callback 是可用的。
生产场景若通过反向代理对外网开放，建议使用 HTTPS 并把代理层回调地址映射为该本机回调，同时在飞书应用配置中放行对应可访问域名。
若需自定义公网 callback（非 localhost），需修改 doOAuthFlow 中 redirectUri 逻辑并重新构建发布。

六、发布（如需维护 npm）

npm version patch # 或指定版本号
npm login --registry https://registry.npmjs.org
npm publish --access public
git tag v1.0.7
git push --tags

七、故障排查

feishu-wiki-mcp 命令未找到：先确认全局安装成功，npm bin -g 在 PATH
启动报 token 错误：检查 APP_ID / APP_SECRET 是否正确、应用是否开通对应权限
OAuth 首次无效：检查 callback URL 是否可达、端口放行是否正常、浏览器可打开授权链接
Token 缓存文件：~/.feishu-wiki-mcp-token.json（每个用户一份，按需清理可强制重新登录）

八、当前版本行为边界

当前实现基于 @modelcontextprotocol/sdk 的 stdio transport，适配本地/远程 MCP 客户端调用
已实现 36 个工具，按需在服务端扩展后可追加

九、Changelog

v1.3.0

新增 wiki_create_node_with_markdown：一步到位在知识库中创建带 Markdown 内容的文档节点。内部自动完成：上传 Markdown → 转换为 docx → 移入知识库指定位置。AI Agent 只需一次调用即可完成之前需要 3 步（create_node → list_blocks → create_blocks）的操作。
新增 drive_upload_file：支持 base64 编码文件上传到飞书云空间，返回 file_token，可用于在文档中插入图片等场景。
增强 doc_import：新增 space_id + parent_wiki_token 可选参数，导入 Markdown 后自动将文档移入知识库，省去手动调用 wiki_move_docs_to_wiki。
增强 doc_create_blocks：
- 补全所有 block_type 文档：新增 11=bullet、12=ordered、15=quote、22=divider 等类型的完整 JSON 示例
- 新增客户端参数校验：block_type 与字段名不匹配时返回明确错误提示（如 block_type=4 需要字段 "heading2"），不再依赖飞书 API 笼统的 invalid param 错误

v1.2.0

bugfix doc_import：修复创建空文档的问题。现在正确实现三步流程：① 上传 md 文件获取 file_token → ② 创建导入任务（md→docx）→ ③ 轮询等待，内容完整导入。
bugfix wiki_delete_node：飞书无公开 wiki 删除端点（DELETE 返回 404）。改为两步删除工作流：本工具先将节点移出 wiki 至云空间根目录，再配合 drive_delete_file 彻底删除底层文件。

v1.1.0

新增 5 个 Docx Blocks 操作工具：doc_list_blocks、doc_get_block、doc_create_blocks、doc_update_block、doc_delete_blocks，支持对飞书文档内容的完整 CRUD
新增 wiki_delete_node、drive_delete_file 删除工具
OAuth 改进：支持 --user-token / --refresh-token 参数和 FEISHU_USER_TOKEN / FEISHU_REFRESH_TOKEN 环境变量，第三方 MCP 客户端无需浏览器即可授权
环境变量支持 FEISHU_APP_ID / FEISHU_APP_SECRET

v1.0.7

初始版本，27 个工具（Wiki、Bitable、IM、权限）