lark-docs-mcp

Minimal MCP server for Codex that reads the plain text content of Lark/Feishu documents.

It can run in two modes:

• MCP server mode for Codex integration
• direct CLI read mode for fast credential and permission checks

What it does

• Exposes one MCP tool: read_lark_doc
• Accepts:
  • direct docx URL
  • direct wiki URL
  • raw doc token
  • raw wiki token
• Fetches:
  • document title
  • latest revision id
  • plain text content

This server is intentionally small and uses only the Python standard library.

Files

• server.py: MCP server implementation
• .env.example: example credentials file

Prerequisites

1. Create a self-built Lark app in the Lark Open Platform.
2. Give the app document read permission.
3. Publish the app or make sure the app availability covers the users/docs you want to access.
4. If a document is private, add the app to that document or otherwise grant it access.

Notes:

• Lark tenant access tokens are fetched through POST /open-apis/auth/v3/tenant_access_token/internal.
• Document metadata is fetched through GET /open-apis/docx/v1/documents/{document_id}.
• Plain text content is fetched through GET /open-apis/docx/v1/documents/{document_id}/raw_content.
• Wiki links are resolved through GET /open-apis/wiki/v2/spaces/get_node?token=....

Setup

1. Create your local credentials file:

cd /Users/helwd/opt/test/lark-docs-mcp
cp .env.example .env

2. Fill in .env with your Lark app credentials.

3. Validate your credentials directly before wiring MCP:

python3 /Users/helwd/opt/test/lark-docs-mcp/server.py \
  --env-file /Users/helwd/opt/test/lark-docs-mcp/.env \
  read "https://example.larksuite.com/docx/AbCdEfGhIjKlMnOpQrStUvWxYz"

If you prefer structured output:

python3 /Users/helwd/opt/test/lark-docs-mcp/server.py \
  --env-file /Users/helwd/opt/test/lark-docs-mcp/.env \
  read "https://example.larksuite.com/docx/AbCdEfGhIjKlMnOpQrStUvWxYz" \
  --format json

4. Smoke test the MCP handshake:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"manual-test","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
| python3 /Users/helwd/opt/test/lark-docs-mcp/server.py --env-file /Users/helwd/opt/test/lark-docs-mcp/.env

5. Register it in Codex:

codex mcp add lark-docs -- \
  python3 /Users/helwd/opt/test/lark-docs-mcp/server.py \
  --env-file /Users/helwd/opt/test/lark-docs-mcp/.env

6. Confirm registration:

codex mcp list

Tool usage

Example tool arguments:

{
  "reference": "https://example.larksuite.com/docx/AbCdEfGhIjKlMnOpQrStUvWxYz",
  "reference_kind": "auto",
  "include_metadata": true,
  "lang": 0
}

You can also pass a wiki link:

{
  "reference": "https://example.larksuite.com/wiki/AbCdEfGhIjKlMnOpQrStUvWxYz"
}

For a raw token:

{
  "reference": "AbCdEfGhIjKlMnOpQrStUvWxYz",
  "reference_kind": "docx"
}

Known limits

• The tool returns plain text, not rich block structure or markdown.
• Wiki resolution is best effort and currently only supports wiki nodes backed by doc or docx.
• If the app lacks access to a document, Lark will return a permission error.