Feishu Wiki

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

• 运行时：Node.js >= 20 + stdio transport（@modelcontextprotocol/sdk）
• 入口：build/index.js
• 当前版本：1.3.1
• 包名：@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 调试台（无需写代码）

1. 打开 open.feishu.cn → 进入你的应用
2. 左侧菜单选择 "开发工具 → API 调试台"
3. 右上角鉴权方式选择 "用户身份（user_access_token）"，点击授权登录
4. 授权完成后，调试台会自动填入 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 能回传到该本机实例。

三、核心流程

1. 启动服务并通过参数选择 tenant 模式或 OAuth 模式
2. MCP 客户端请求对应 tool
3. 服务器内部自动获取并刷新 token（~/.feishu-wiki-mcp-token.json）
4. 使用 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 代替）

推荐环境变量

• FEISHU_APP_ID
• FEISHU_APP_SECRET
• FEISHU_USER_TOKEN（预置模式，无需浏览器）
• FEISHU_REFRESH_TOKEN（配合 user token 自动续期）
• FEISHU_OAUTH=true/false（已废弃，建议改用 user token 模式）

示例 .env

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=secret_xxx
FEISHU_OAUTH=true
FEISHU_MCP_PORT=3001

示例启动脚本（避免在命令行直接暴露明文）

set -a
source .env
set +a

if [ "${FEISHU_OAUTH}" = "true" ]; then
  feishu-wiki-mcp --app-id "$FEISHU_APP_ID" --app-secret "$FEISHU_APP_SECRET" --oauth --port "${FEISHU_MCP_PORT:-3001}"
else
  feishu-wiki-mcp --app-id "$FEISHU_APP_ID" --app-secret "$FEISHU_APP_SECRET"
fi

版本与发布一致性

• 当前代码版本：1.3.1（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、权限）