MCP Lark Doc Manage

A Model Context Protocol server for searching and accessing Lark(Feishu) documents.

Important: Before using this MCP Server, you need to have a Lark Enterprise Application. If you haven't created one yet, please follow the setup instructions below.

Features

Document Content Access

Supports both Lark Doc and Wiki document types
Automatically handles document type detection and ID extraction
Returns raw content in text format for LLM processing

Authentication

OAuth-based user authentication
Automatic token refresh and expiration management
Customizable OAuth callback server

Error Handling

Comprehensive error reporting for authentication issues
Clear feedback for invalid document URLs
Detailed error messages for troubleshooting

Installation

uvx mcp-lark-doc-manage

Configuration

Create Your Lark Enterprise Application

Visit Lark Open Platform
Click "Developer Console" in the top right corner
Click "Create Custom App"
Fill in the basic information:
- App Name
- App Description
- App Icon
In the "Security Settings" section:
- Add your domain to "Request Domain Name Whitelist"
- Configure OAuth 2.0 settings
Enable required capabilities and apply for permissions in "Permission Management"
Submit for review and wait for approval

For detailed instructions, see Custom App Development Process.

Get App ID and App Secret

Get App ID:
- Go to your app in Developer Console
- Find "App ID" (also called "Client ID") in "Credentials & Basic Info"
- It usually starts with "cli_" for internal apps
Get App Secret:
- In the same "Credentials & Basic Info" page
- Find "App Secret" (also called "Client Secret")
- Click "View" to see the secret
- Note: Keep your App Secret secure and never share it publicly

Get Folder Token

To get a folder token:

Open the target folder in Lark
Copy the folder URL, for example: https://xxx.feishu.cn/drive/folder/xxx
The last segment in the URL is your folder token
Alternative method:
- Use the Drive API to list folders
- Find the target folder's token in the response

Note: Make sure your app has the drive:drive:readonly permission to access folders.

Required Permissions

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

Environment Variables

Before using this MCP server, you need to set up your Lark application credentials:

Create a Lark application in Lark Open Platform
Get your App ID and App Secret
Configure environment variables:

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)

Usage

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

Note: Replace /path/to/your/uvx with your actual uvx path (e.g., /Users/username/anaconda3/bin/uvx).

Available Tools

get_lark_doc_content
- Purpose: Retrieve document content from Lark
- Args: documentUrl (string) - The URL of the Lark document
- Returns: Document content in text format
- Supports:
  - Doc URLs: https://xxx.feishu.cn/docx/xxxxx
  - Wiki URLs: https://xxx.feishu.cn/wiki/xxxxx
search_wiki
- Purpose: Search documents in Lark Wiki
- Args:
  - query (string) - Search keywords
  - page_size (int, optional) - Number of results to return (default: 10)
- Returns: JSON string containing search results with following fields:
  - title: Document title
  - url: Document URL
  - create_time: Document creation time
  - update_time: Document last update time
list_folder_content
- Purpose: List contents of a specified folder
- Args:
  - page_size (int, optional) - Number of results to return (default: 10)
- Returns: JSON string containing file list with following fields:
  - name: File name
  - type: File type
  - token: File token
  - url: File URL
  - create_time: Creation time
  - edit_time: Last edit time
  - owner_id: Owner ID
create_doc
- Purpose: Create a new Lark document with content
- Args:
  - title (string) - Document title
  - content (string, optional) - Document content in Markdown format
  - target_space_id (string, optional) - Target wiki space ID to move the document to
- Returns: JSON string containing:
  - document_id: Created document ID
  - title: Document title
  - url: Document URL
- Features:
  - Supports Markdown content conversion
  - Optional wiki space integration
  - Automatic folder placement

Error Messages

Common error messages and their solutions:

"Lark client not properly initialized": Check your LARK_APP_ID and LARK_APP_SECRET
"Invalid Lark document URL format": Verify the document URL format
"Failed to get document content": Check document permissions and token validity
"Failed to get app access token": Check your application credentials and network connection
"Failed to get wiki document real ID": Check if the wiki document exists and you have proper permissions
"Document content is empty": The document might be empty or you might not have access to its content
"Authorization timeout": User didn't complete authorization within 5 minutes
"Folder token not configured": Check your FOLDER_TOKEN environment variable

Development Notes

OAuth Callback Server

Default configuration:

Host: localhost
Port: 9997

Customize via environment variables:

OAUTH_HOST: Set callback server host
OAUTH_PORT: Set callback server port

License

MIT License