MCP Lark 文档管理

一个用于搜索和访问 Lark(飞书) 文档的模型上下文协议服务器。

中文文档

重要提示: 在使用此 MCP 服务器之前，您需要拥有一个飞书企业应用。如果您尚未创建，请按照以下设置说明进行操作。

功能

文档内容访问

• 支持飞书文档和 Wiki 文档类型
• 自动处理文档类型检测和 ID 提取
• 以文本格式返回原始内容，供 LLM 处理

身份验证

• 基于 OAuth 的用户身份验证
• 自动令牌刷新和过期管理
• 可自定义的 OAuth 回调服务器

错误处理

• 针对身份验证问题的全面错误报告
• 针对无效文档 URL 的清晰反馈
• 用于故障排除的详细错误消息

安装

uvx mcp-lark-doc-manage

配置

创建您的飞书企业应用

1. 访问 飞书开放平台
2. 点击右上角的“开发者后台”
3. 点击“创建企业自建应用”
4. 填写基本信息：
   • 应用名称
   • 应用描述
   • 应用图标
5. 在“安全设置”部分：
   • 将您的域名添加到“请求域名白名单”
   • 配置 OAuth 2.0 设置
6. 在“权限管理”中启用所需能力并申请权限
7. 提交审核并等待批准

有关详细说明，请参阅 企业自建应用开发流程。

获取 App ID 和 App Secret

1. 获取 App ID：

   • 在 开发者后台 中转到您的应用
   • 在“凭证与基础信息”中找到“App ID”（也称为“Client ID”）
   • 对于内部应用，通常以 "cli_" 开头

2. 获取 App Secret：

   • 在同一“凭证与基础信息”页面中
   • 找到“App Secret”（也称为“Client Secret”）
   • 点击“查看”以查看密钥
   • 注意：请确保您的 App Secret 安全，切勿公开分享

获取文件夹 Token

要获取文件夹 token：

1. 在飞书中打开目标文件夹
2. 复制文件夹 URL，例如：https://xxx.feishu.cn/drive/folder/xxx
3. URL 中的最后一段是您的文件夹 token
4. 替代方法：
   • 使用 Drive API 列出文件夹
   • 在响应中找到目标文件夹的 token

注意：确保您的应用具有 drive:drive:readonly 权限才能访问文件夹。

必需权限

wiki:node:read      # Wiki 节点读取权限
docx:document:readonly   # 文档只读访问权限
search:docs:read    # 文档搜索权限
drive:drive:readonly    # Drive 只读访问权限

环境变量

在使用此 MCP 服务器之前，您需要设置您的飞书应用程序凭据：

1. 在飞书开放平台中创建一个飞书应用程序
2. 获取您的 App ID 和 App Secret
3. 配置环境变量：

export LARK_APP_ID="your_app_id"
export LARK_APP_SECRET="your_app_secret"
export FOLDER_TOKEN="your_folder_token"    # 指定的文件夹 token
export OAUTH_HOST="localhost"              # OAuth 回调服务器主机 (默认: localhost)
export OAUTH_PORT="9997"                   # OAuth 回调服务器端口 (默认: localhost)

用法

在 Claude desktop 中配置：

"mcpServers": {
    "lark_doc": {
        "command": "/path/to/your/uvx",
        "args": [
            "mcp-lark-doc-manage"
        ],
        "env": {
            "LARK_APP_ID": "your_app_id",
            "LARK_APP_SECRET": "your_app_secret",
            "OAUTH_HOST": "localhost",
            "OAUTH_PORT": "9997",
            "FOLDER_TOKEN": "your_folder_token",
            "DEBUG": "1"  // 可选，启用调试模式
        }
    }
}

注意：将 /path/to/your/uvx 替换为您实际的 uvx 路径（例如，/Users/username/anaconda3/bin/uvx）。

可用工具

1. get_lark_doc_content

   • 目的：从飞书检索文档内容
   • 参数：documentUrl (string) - 飞书文档的 URL
   • 返回：文本格式的文档内容
   • 支持：
     • 文档 URL：https://xxx.feishu.cn/docx/xxxxx
     • Wiki URL：https://xxx.feishu.cn/wiki/xxxxx

2. search_wiki

   • 目的：在飞书 Wiki 中搜索文档
   • 参数：
     • query (string) - 搜索关键词
     • page_size (int, optional) - 返回的结果数量（默认：10）
   • 返回：包含搜索结果的 JSON 字符串，包含以下字段：
     • title：文档标题
     • url：文档 URL
     • create_time：文档创建时间
     • update_time：文档上次更新时间

3. list_folder_content

   • 目的：列出指定文件夹的内容
   • 参数：
     • page_size (int, optional) - 返回的结果数量（默认：10）
   • 返回：包含文件列表的 JSON 字符串，包含以下字段：
     • name：文件名
     • type：文件类型
     • token：文件 token
     • url：文件 URL
     • create_time：创建时间
     • edit_time：上次编辑时间
     • owner_id：所有者 ID

4. create_doc

   • 目的：创建包含内容的新飞书文档
   • 参数：
     • title (string) - 文档标题
     • content (string, optional) - Markdown 格式的文档内容
     • target_space_id (string, optional) - 目标 wiki 空间 ID，用于将文档移动到该空间
   • 返回：包含以下内容的 JSON 字符串：
     • document_id：已创建的文档 ID
     • title：文档标题
     • url：文档 URL
   • 功能：
     • 支持 Markdown 内容转换
     • 可选的 wiki 空间集成
     • 自动文件夹放置

错误消息

常见错误消息及其解决方案：

• "Lark client not properly initialized"（飞书客户端未正确初始化）：检查您的 LARK_APP_ID 和 LARK_APP_SECRET
• "Invalid Lark document URL format"（飞书文档 URL 格式无效）：验证文档 URL 格式
• "Failed to get document content"（无法获取文档内容）：检查文档权限和 token 有效性
• "Failed to get app access token"（无法获取应用访问令牌）：检查您的应用程序凭据和网络连接
• "Failed to get wiki document real ID"（无法获取 wiki 文档的真实 ID）：检查 wiki 文档是否存在以及您是否具有适当的权限
• "Document content is empty"（文档内容为空）：文档可能为空，或者您可能无权访问其内容
• "Authorization timeout"（授权超时）：用户未在 5 分钟内完成授权
• "Folder token not configured"（未配置文件夹 token）：检查您的 FOLDER_TOKEN 环境变量

开发说明

OAuth 回调服务器

默认配置：

• Host：localhost
• Port：9997

通过环境变量自定义：

• OAUTH_HOST：设置回调服务器主机
• OAUTH_PORT：设置回调服务器端口

许可证

MIT 许可证