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 种模式：追加、覆盖、范围替换、全文替换、前/后插入、删除 |
前置条件
- Node.js >= 18
- 飞书开放平台应用（创建应用）
- 记下 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 一致 |
使用
首次认证
- 在 Claude Code 中调用
feishu_auth（mode=start） - 在浏览器中打开返回的授权链接
- 点击授权，页面显示"授权成功"即完成
认证后 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-ToolsLicense
MIT
