Feishu Reader

This is a desktop application built with Python and PyQt6, designed to help users quickly extract Feishu documents (Docx / Wiki) and convert them into Markdown format for local storage.

🌟 Features

• Graphical User Interface: Provides a clean and easy-to-use PyQt6 desktop interface.

• One-Click Extraction: Supports pasting Feishu document/wiki links to fetch and generate .md files with a single click.

• Comprehensive Format Support: Parses and supports common Feishu document elements such as text, multi-level headings, code blocks, lists, quotes, tables, and Mermaid diagrams.

• Image Localization: Automatically downloads images within the document to a local assets_<doc_token>/ directory and generates relative path references in the Markdown file.

• Permissions & Authentication:

  • Enter the Feishu App ID and App Secret directly in the interface to obtain an Access Token with one click.

  • Supports manual Token entry and a "Remember" checkbox to save credentials locally.

• Local Storage: Automatically generates filenames with timestamps and saves them to a user-specified directory.

Related MCP server: Feishu MCP Server

🔑 Feishu App Configuration

This tool accesses documents via a Custom App on the Feishu Open Platform. The following configuration is required for the first use.

Step 1: Create a Custom App

1. Open the Feishu Open Platform and log in with an administrator account.

2. Go to the Developer Console → Click Create App in the top right corner → Select Custom App.

3. Enter the app name (e.g., "Document Extraction Tool"), description, upload an icon, and click Confirm.

4. Go to the app details page, and under the Credentials & Basic Info tab, copy:

   • App ID (e.g., cli_xxxxxxxxxxxxxxxx)

   • App Secret (Click "View" to copy)

Step 2: Enable Required Permissions

Go to the app details page → Permissions & Scopes → Search for and enable the following permissions:

Note: After enabling permissions, go to the Version Management & Release tab, create and release a version for the permissions to take effect.

Step 3: Share Documents with the App

By default, Feishu documents are only visible to authorized personnel. You must share the target document (or knowledge base) with the app bot:

1. Open the target Feishu document and click Share in the top right corner.

2. Search for your App Name in the sharing dialog and set the permission to Can View.

3. Click Confirm, and the app will be able to access the document.

For Wiki documents, you must add the app bot in the Member Management section of the Wiki and grant it viewing permissions.

🛠️ Installation and Running

Requirements

• Python 3.10 or higher

Install Dependencies

pip install -r requirements.txt

Launch Desktop App

python main.py

🔌 MCP Server Mode

Supports running as an MCP server, making it easy to call directly from AI tools like Claude and Cursor.

Configure Environment Variables

export FEISHU_APP_ID="cli_xxxxxxxxxxxxx"
export FEISHU_APP_SECRET="xxxxxxxxxxxxxxxx"

Start MCP Server

python mcp_server.py

Configure for Claude / Cursor

Add the following to ~/.claude.json or your project's MCP configuration:

{
  "mcpServers": {
    "feishu-reader": {
      "command": "python",
      "args": ["mcp_server.py"],
      "env": {
        "FEISHU_APP_ID": "cli_xxxxxxxxxxxxx",
        "FEISHU_APP_SECRET": "xxxxxxxxxxxxxxxx"
      },
      "workingDirectory": "/path/to/feishu-reader-mcp"
    }
  }
}

📖 User Guide

1. Enter Credentials: Enter the App ID and App Secret of your Feishu custom app at the top of the interface (saved automatically after first use).

2. Get Token: Click the [Refresh] button next to the Access Token row to automatically fetch and fill the Token; you can also paste an existing Token manually.

3. Paste Document Link: Paste the Feishu document or Wiki page link into the "Document URL" input box (supports /docx/, /doc/, and /wiki/ type links).

4. Start Extraction: Click [Start Extraction] and select the directory to save the Markdown file in the pop-up window.

5. Wait for Completion: The log area at the bottom will display progress in real-time. Once finished, find the .md file and the assets_xxx/ image directory in the target folder.

📄 Project Structure

💡 Notes

• This tool is adapted for the new Feishu document format (based on /docx/v1/documents OpenAPI); older document formats may have formatting discrepancies.

• Image downloading requires the app to have the docs:document.media:download permission enabled and the document to be correctly shared with the app bot; otherwise, images will be skipped and the reason will be logged.

• API calls have rate limits (5 QPS / 10,000 per day); please avoid frequent repeated extractions for large documents.

• The Token is valid for approximately 2 hours by default; click [Refresh] to re-obtain it after expiration.