feishu-doc-mcp

飞书云文档 MCP Server，为 Claude Code 提供飞书文档的创建、读取、编辑能力。

通过代理飞书 MCP 网关（mcp.feishu.cn），以用户身份（User Access Token）操作文档，支持 token 自动刷新，一次授权长期使用。

功能

工具	说明
feishu_auth	OAuth 2.0 认证（PKCE + offline_access），首次使用需在浏览器授权
feishu_fetch_doc	读取文档内容，返回 Markdown 格式，支持分页
feishu_create_doc	从 Markdown 创建新文档，可指定文件夹/知识库位置
feishu_update_doc	更新文档，支持 7 种模式：追加、覆盖、范围替换、全文替换、前/后插入、删除

前置条件

1. Node.js >= 18
2. 飞书开放平台应用（创建应用）
   • 记下 App ID 和 App Secret
   • 在 安全设置 → 重定向 URL 中添加：http://localhost:<端口>/callback（默认端口 9876）
   • 在 权限管理 中开通需要的权限（如 docx:document）

安装

git clone https://github.com/ShacklesLay/feishu-doc-mcp.git
cd feishu-doc-mcp
npm install

配置 Claude Code

编辑 ~/.claude.json，在 mcpServers 中添加：

{
  "mcpServers": {
    "feishu-doc": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "export FEISHU_APP_ID=你的AppID FEISHU_APP_SECRET=你的AppSecret; exec node /path/to/feishu-doc-mcp/server.mjs"
      ]
    }
  }
}

环境变量

变量	必填	说明
FEISHU_APP_ID	是	飞书应用 App ID
FEISHU_APP_SECRET	是	飞书应用 App Secret
FEISHU_AUTH_PORT	否	OAuth 回调端口，默认 9876，需与飞书后台重定向 URL 一致

使用

首次认证

1. 在 Claude Code 中调用 feishu_auth（mode=start）
2. 在浏览器中打开返回的授权链接
3. 点击授权，页面显示"授权成功"即完成

认证后 token 会自动刷新（通过 refresh_token），无需重复授权。

读取文档

feishu_fetch_doc(doc_id: "文档ID或URL")

支持分页参数 offset 和 limit。

创建文档

feishu_create_doc(title: "标题", markdown: "# 内容")

可选参数指定位置：

• folder_token — 放入指定文件夹
• wiki_space — 放入知识空间（my_library 表示个人空间）
• wiki_node — 放入知识库节点下

三者互斥，只能选一个。

更新文档

feishu_update_doc(doc_id: "文档ID", mode: "append", markdown: "追加的内容")

7 种更新模式：

模式	说明
append	在文档末尾追加
overwrite	覆盖整个文档
replace_range	替换指定范围（配合 selection_by_title 或 selection_with_ellipsis）
replace_all	全文查找替换
insert_before	在指定位置前插入
insert_after	在指定位置后插入
delete_range	删除指定范围

检查认证状态

feishu_auth(mode: "status")

Token 存储

Token 以 JSON 明文存储在 ~/.local/share/feishu-doc-mcp/tokens.json，仅限本地使用。

架构

Claude Code
  └── feishu-doc MCP Server (stdio)
        ├── feishu_auth     → OAuth 2.0 + PKCE → 飞书开放平台
        ├── feishu_fetch_doc ─┐
        ├── feishu_create_doc ├→ JSON-RPC 2.0 → mcp.feishu.cn/mcp
        └── feishu_update_doc ─┘
              Headers: X-Lark-MCP-UAT, X-Lark-MCP-Allowed-Tools

License

MIT