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

本项目是面向 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 有效期说明

3. 安装后直接运行

npm install -g @akaknele/feishu-wiki-mcp@1.3.1
feishu-wiki-mcp --app-id <APP_ID> --app-secret <APP_SECRET>

或使用 npx：

npx @akaknele/feishu-wiki-mcp@1.3.1 --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"]
    }
  }
}

Related MCP server: lark-mcp

二、外网网络（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）

文档（Docx）

多维表格（Bitable）

IM 与联系人

权限与删除

说明

• 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、权限）