mcpField
F
feishu-doc-reader

feishu-doc-reader

github.com/zhangyongcunDocuments0132 installsUpdated 35w ago
Repository

About feishu-doc-reader

feishu-doc-reader is a command-line skill for extracting content from Feishu and Lark documents through their official Open API. It handles wiki links and tokens as well as several document types, with configuration for either service region.

Key features

  1. 01Read Docx content as Markdown
  2. 02Read legacy Doc and Sheet content
  3. 03Resolve wiki links and tokens
  4. 04Retrieve raw document blocks
  5. 05Configure Feishu or Lark API access

Use cases

  1. 01Extract content from a Feishu or Lark Docx
  2. 02Read spreadsheet data from a Sheet
  3. 03Resolve a wiki page to its underlying document
  4. 04Inspect raw blocks from a document

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/zhangyongcun/feishu-doc-reader --skill feishu-doc-reader

After installing, type/feishu-doc-readerin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

README.md
.gitignore
CONTRIBUTING.md
requirements.txt
USAGE_EXAMPLES.md
INTEGRATION.md
test_optimization.py
reference/
feishu_config_sample.json
scripts/
get_blocks.sh
package_skill.py
get_feishu_doc_blocks.py
read_doc.sh
test_blocks_integration.py
test_auth.py
read_feishu_doc.py

Details

From the project README

Feishu/Lark Document Reader

Read and extract content from Feishu (飞书) and Lark documents using the official Open API. Supports both Feishu China (open.feishu.cn) and Lark International (open.larksuite.com).

Configuration

Set Up Credentials
  1. Create ./reference/feishu_config.json from the sample:
{
  "app_id": "your_feishu_app_id",
  "app_secret": "your_feishu_app_secret",
  "api_base": "https://open.larksuite.com"
}

Set api_base to:

  • https://open.feishu.cn — Feishu China
  • https://open.larksuite.com — Lark International
  1. Secure the file:
chmod 600 ./reference/feishu_config.json

Alternatively, use environment variables: FEISHU_APP_ID, FEISHU_APP_SECRET, FEISHU_API_BASE.

Usage

Read Documents

The main script accepts wiki URLs, wiki tokens, or document tokens:

# Wiki URL (auto-extracts token and resolves to document)
python scripts/read_feishu_doc.py "https://tenant.larksuite.com/wiki/XYZ123"

# Wiki token (auto-resolves)
python scripts/read_feishu_doc.py "XYZ123"

# Document token (direct)
python scripts/read_feishu_doc.py "docx_AbCdEfGh"

# Simplified Markdown output
python scripts/read_feishu_doc.py "docx_AbCdEfGh" --format simple

# Read a spreadsheet
python scripts/read_feishu_doc.py "sheet_token" --type sheet
Get Raw Document Blocks
python scripts/get_feishu_doc_blocks.py "docx_AbCdEfGh"
Shell Wrappers
./scripts/read_doc.sh "docx_token"
./scripts/get_blocks.sh "docx_token"
Test Authentication
python scripts/test_auth.py "app_id" "app_secret" "https://open.larksuite.com"

Supported Document Types

  • Docx (new docs): Full Markdown extraction with tables, headings, code, lists
  • Doc (legacy): Basic metadata and content
  • Sheet: Spreadsheet data extraction
  • Wiki: Auto-resolved to underlying document type via wiki API

API Permissions Required

  • docx:document:readonly — Read document content
  • wiki:wiki:readonly — Read wiki pages (for wiki URL/token support)
  • sheets:spreadsheet:readonly — Read spreadsheets (optional)

Error Handling

  • 401: Check App ID / App Secret
  • 403: Grant API permissions; ensure document is shared with app
  • 404: Verify document token
  • Wrong region: Use open.larksuite.com for Lark International

Security

  • Never commit reference/feishu_config.json (listed in .gitignore)
  • Use chmod 600 for credential files
  • Access tokens are cached in memory only

Comments

Markdown supported