Lark_doc

MCP Lark Doc Manage

用于搜索和访问 Lark（Feishu）文档的 Model Context Protocol 服务。

中文文档

重要提示：使用此 MCP 服务前，你需要拥有一个 Lark 企业应用。如果你尚未创建，请按照以下设置说明操作。

功能

文档内容访问

• 支持 Lark Doc 和 Wiki 两种文档类型
• 自动识别文档类型并提取 ID
• 以文本格式返回原始内容，供大模型处理

身份验证

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

错误处理

• 全面报告身份验证问题
• 清晰提示无效的文档 URL
• 提供详细的错误信息，便于排查问题

安装

uvx mcp-lark-doc-manage

配置

创建 Lark 企业应用

1. 访问 Lark Open Platform
2. 点击右上角的“Developer Console”
3. 点击“Create Custom App”
4. 填写基本信息：
   • 应用名称
   • 应用描述
   • 应用图标
5. 在“Security Settings”部分：
   • 将你的域名添加到“Request Domain Name Whitelist”
   • 配置 OAuth 2.0 设置
6. 在“Permission Management”中启用所需功能并申请权限
7. 提交审核并等待批准

详细说明请参阅 Custom App Development Process。

获取 App ID 和 App Secret

1. 获取 App ID：

   • 在 Developer Console 中打开你的应用
   • 在“Credentials & Basic Info”中找到“App ID”（也称为“Client ID”）
   • 内部应用的 App ID 通常以“cli_”开头

2. 获取 App Secret：

   • 打开同一“Credentials & Basic Info”页面
   • 找到“App Secret”（也称为“Client Secret”）
   • 点击“View”查看密钥
   • 注意：妥善保管 App Secret，切勿公开分享

获取文件夹 Token

获取文件夹 Token：

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

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

所需权限

wiki:node:read      # Wiki node read access
docx:document:readonly   # Document read-only access
search:docs:read    # Document search access
drive:drive:readonly    # Drive read-only access

环境变量

使用此 MCP 服务前，你需要设置 Lark 应用凭据：

1. 在 Lark Open Platform 创建 Lark 应用
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"    # Specified folder token
export OAUTH_HOST="localhost"              # OAuth callback server host (default: localhost)
export OAUTH_PORT="9997"                   # OAuth callback server port (default: 9997)

使用方法

在 Claude 桌面应用中配置：

"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"  // optional, enable debug mode
        }
    }
}

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

可用工具

1. get_lark_doc_content

   • 用途：从 Lark 获取文档内容
   • 参数：documentUrl（string）- Lark 文档的 URL
   • 返回：文本格式的文档内容
   • 支持：
     • 文档 URL：https://xxx.feishu.cn/docx/xxxxx
     • Wiki URL：https://xxx.feishu.cn/wiki/xxxxx

2. search_wiki

   • 用途：搜索 Lark Wiki 中的文档
   • 参数：
     • query（int）- 搜索关键词
     • page_size（int，可选）- 返回结果数量（默认值：10）
   • 返回：包含以下字段的 JSON 字符串，其中包含搜索结果：
     • title：文档标题
     • url：文档 URL
     • create_time：文档创建时间
     • update_time：文档最后更新时间

3. list_folder_content

   • 用途：列出指定文件夹中的内容
   • 参数：
     • page_size（int，可选）- 返回结果数量（默认值：10）
   • 返回：包含以下字段的文件列表 JSON 字符串：
     • name：文件名
     • type：文件类型
     • token：文件令牌
     • url：文件 URL
     • create_time：创建时间
     • edit_time：最后编辑时间
     • owner_id：所有者 ID

4. create_doc

   • 用途：创建包含内容的新 Lark 文档
   • 参数：
     • title（string）- 文档标题
     • content（string，可选）- Markdown 格式的文档内容
     • target_space_id（string，可选）- 要将文档移至的目标 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 格式
• "Failed to get document content"：检查文档权限和令牌有效性
• "Failed to get app access token"：检查应用凭据和网络连接
• "Failed to get wiki document real ID"：检查 Wiki 文档是否存在，以及你是否拥有适当权限
• "Document content is empty"：文档可能为空，或者你可能无权访问其内容
• "Authorization timeout"：用户未能在 5 分钟内完成授权
• "Folder token not configured"：检查你的 FOLDER_TOKEN 环境变量

开发说明

OAuth 回调服务器

默认配置：

• 主机：localhost
• 端口：9997

通过环境变量自定义：

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

许可证

MIT 许可证