Feishu MCP

MCP server for querying and updating Feishu Base boards and querying Feishu docs through lark-cli.

This package exposes Feishu Base read/write tools and document search/fetch tools to MCP clients such as Codex, Claude Desktop, or other clients that support stdio MCP servers.

Requirements

• Node.js 18 or later
• lark-cli installed and available in PATH
• A valid lark-cli login session with access to the target Feishu Base

Check your Feishu CLI login before using the MCP server:

lark-cli whoami

Install

Use it directly with npx:

npx -y feishu-mcp-zjt

Or install it globally:

npm install -g feishu-mcp-zjt
feishu-mcp

MCP Client Config

For the fastest and most stable startup, install the package globally and point your MCP client at the installed feishu-mcp command:

{
  "mcpServers": {
    "feishu-mcp": {
      "command": "feishu-mcp"
    }
  }
}

If lark-cli is not in the default PATH, pass its absolute path through FEISHU_CLI_BIN:

{
  "mcpServers": {
    "feishu-mcp": {
      "command": "feishu-mcp",
      "env": {
        "FEISHU_CLI_BIN": "/absolute/path/to/lark-cli"
      }
    }
  }
}

You can also tune or disable the in-process read cache:

{
  "mcpServers": {
    "feishu-mcp": {
      "command": "feishu-mcp",
      "env": {
        "FEISHU_MCP_CACHE_TTL_MS": "300000"
      }
    }
  }
}

Set FEISHU_MCP_CACHE_TTL_MS to 0 to disable caching. The default is 300000 milliseconds.

Available Tools

• whoami: show the current Feishu CLI identity and token status
• resolve_board: resolve a Feishu board title or URL to a Base token
• search_docs: search Feishu docs, wiki pages, and spreadsheet files by keyword
• fetch_doc: fetch a Feishu document or wiki page by URL or token
• update_doc: safely update a Feishu document or wiki page with narrow edits only
• update_record: update a single record in a Base table
• batch_update_records: update multiple records in a Base table with the same patch
• list_blocks: list dashboards, tables, workflows, and other Base blocks
• list_tables: list tables in a Base
• list_fields: list fields for a Base table
• query_default_work_items: fast query for the default 需求管理看板 bugs, tasks, requirements, and iterations with built-in token, table IDs, and core fields
• search_records: search records in a Base table by keyword
• list_records: list records in a Base table with pagination
• get_record: fetch one or more records by record ID
• expand_linked_records: expand link fields and fetch linked records

Local Development

npm install
npm start

Run a syntax check:

npm run check

Preview the npm package contents:

npm run pack:dry-run

Publish

Update the version before publishing:

npm version patch
npm publish

For an internal npm registry, configure registry through your .npmrc or publish command. If publishing this package publicly, keep publishConfig.access set to public.

Environment

• FEISHU_CLI_BIN: optional path to the lark-cli executable. Defaults to lark-cli.
• FEISHU_MCP_CACHE_TTL_MS: optional TTL for cached read calls in milliseconds. Defaults to 300000; set to 0 to disable.

Notes

• The server shells out to lark-cli, so it reuses the current machine's Feishu login state.
• Read calls such as table/field listing, record search, record get, document search/fetch, and board resolve are cached in memory for the configured TTL. Update calls are never cached.
• Users must have permission to the Feishu Base they want to query.
• Write tools only update the fields you pass in patch; prefer narrow patches and confirm field names with list_fields first.
• For tasks that can affect multiple records, prefer batch_update_records only when every target should receive the same patch.
• Keep document work read-first: use search_docs to find the target, then fetch_doc to inspect it before any follow-up action.
• update_doc only allows str_replace, block_insert_after, block_replace, and block_delete; it does not expose overwrite, append, or move/copy operations.
• block_delete requires an explicit confirm flag in the tool input.
• Tool responses are returned as formatted JSON text for easy inspection by MCP clients.