Feishu-MCP: Giving Coding Agents Read and Write Access to Lark Docs and Tasks

The gap Feishu-MCP fills between an agent and a Lark workspace

An AI coding tool can read files in your repository. It cannot open a Feishu document, walk its block tree, insert a table, or file a task against the right colleague. Feishu-MCP exists to close that gap. The README frames the goal as giving Cursor, Windsurf, Cline and similar tools the ability to access, edit and structure Feishu documents, and it extends that to task management and user lookup. The audience is narrow and identifiable: teams whose specs, meeting notes and task tracking sit in Feishu or Lark, and who want an agent to operate on that content directly instead of on a copy. If your documentation lives in the repository, this project adds a credential surface and a network dependency for nothing. The tool list makes the intent concrete. There are document tools for creating, inspecting and editing blocks, folder tools, a search tool, and higher-level capabilities such as table creation, image upload and whiteboard content retrieval. Task tools cover listing, creating with subtasks, updating and deleting, and user tools resolve people by name or by ID. That last pair is what turns the project from a document editor into something that can assign work, and it is also what forces the heavier authentication path described below.

Block-level editing over the Feishu open API, not a Markdown round trip

The mechanism the README describes is not a text import. Tools such as get_feishu_document_blocks retrieve the block structure of a document, and batch_create_feishu_blocks, update_feishu_block_text and delete_feishu_document_blocks operate on that structure. So the agent works at the level of Feishu's own content model rather than converting a document to Markdown, editing it, and pushing it back. That distinction explains why the supported formatting list is as long as it is: bold, italic, underline, strikethrough and inline code; text colours; alignment; heading levels 1 through 9; code blocks with language highlighting; ordered and unordered lists; local and remote images; LaTeX formulas; mermaid diagrams; and tables whose cells can themselves contain headings, lists and code blocks. A Markdown round trip would flatten most of that. The cost of the block model is that the agent has to reason about document structure. Creating content is a sequence of calls, which is why the project ships batch operations and why the roadmap lists reducing multi-step calls as an open item. There is a second surface worth noting: the README documents a standalone feishu-tool CLI invoked as feishu-tool <tool-name> '<json>', which runs the same tools without starting an MCP server. A companion repository, Feishu-Skill, is described as guidance for agents such as Claude Code on when to use that CLI. Two front ends over one tool layer is a reasonable design, and the 0.2.6 release notes describe extracting a Tool API layer to unify parameter validation, data conversion and error mapping across them.

Getting it running: npx, flags, and the .env path

The fastest route in the README is a single npx invocation: npx feishu-mcp@latest --feishu-app-id=<your app id> --feishu-app-secret=<your app secret> --feishu-auth-type=<tenant/user> --enabled-modules=<document,task>. Note the enabled-modules flag: the document and task surfaces can be switched on separately, so an agent that should only read docs does not need the task tools exposed. The alternative is a local clone, followed by copying .env.example to .env and filling in FEISHU_APP_ID, FEISHU_APP_SECRET, PORT and FEISHU_AUTH_TYPE. The README states plainly that Feishu application configuration must be completed first or the tool will not work, and points to a separate FEISHU_CONFIG.md walkthrough for registering the app, configuring permissions and granting document access. That last step is the one people miss. Creating the app is not enough; the app has to be given access to the specific documents and folders it should touch. Two other knobs appear in the changelog. FEISHU_SCOPE_VALIDATION, or the equivalent --feishu-scope-validation flag, was introduced in 0.2.0 to control a startup check of the app's granted scopes, defaulting to enabled. And 0.2.2 moved token and credential caching into a system-level configuration directory, which matters if you run the server from more than one working directory.

Two auth modes, and only one of them reaches tasks

The auth-type flag accepts tenant or user, and the README is explicit that task management and user information require user authentication. That is the single most consequential configuration decision in the project. A tenant token is the simpler, more predictable option and is enough for document and folder work. A user token is what lets the agent see and modify the tasks belonging to a person and resolve colleagues by name, and it brings a refresh problem that the changelog tracks across releases: user_access_token auto-refresh arrived in 0.1.6, a stdio-mode user authentication failure was fixed in 0.1.9, and multi-user user authentication, described as one deployment serving several people, landed in 0.1.3. Read that sequence as a signal. The user-auth path has been the source of repeated fixes, and the 0.1.7 entry on authorization scope validation exists precisely because a misconfigured app produces confusing failures rather than clear ones. The scope validation feature is the project's own admission that setup errors were common enough to deserve a preflight check. If you disable it with FEISHU_SCOPE_VALIDATION, you are removing the thing that tells you why a call failed.

Where this is the wrong tool

Feishu-MCP is a write-capable bridge into a shared workspace, and that shapes its failure modes. The documentation does not describe a dry-run mode, a diff preview, or an undo for block operations. An agent that misreads a request can call delete_feishu_document_blocks or batch delete tasks, and the README's tool table lists those without any stated guardrail. Treat the enabled-modules flag as the real safety boundary: if a session only needs to read a spec, do not expose the task module at all. A second limitation is coverage. The README's own roadmap still lists extracting the Feishu app ID and secret from environment variables so that a single service can be shared across teams as an open item, which means the current shape assumes credentials in the server's environment or in client configuration rather than a multi-tenant arrangement. Third, several entries in the plan are marked as completed but annotated with a note that the Feishu application configuration changed, including whiteboard creation and knowledge base traversal. That phrasing suggests behaviour that shifted with the platform rather than with the code, and it is worth testing those specific tools against your tenant before depending on them. Finally, the project is a single-maintainer TypeScript repository under MIT. If your organization cannot accept an unaffiliated dependency holding a token that can edit documents and delete tasks, this is not the tool for you regardless of how well it works.

Alternatives and the actual difference in approach

The obvious alternative is not another MCP server. It is exporting the document and letting the agent work on a file. Feishu documents can be exported, and an agent that reads a local Markdown file needs no app registration, no scopes, no token refresh and no network round trip. The difference is in what you lose. An exported file is a snapshot: edits do not go back, block types that do not survive export are gone, and anything the agent writes has to be pasted in by a person. Feishu-MCP trades that simplicity for in-place operation, which is the only way to make comments, tables, mermaid diagrams and whiteboards part of the loop. The second alternative is a direct integration written against Feishu's open API for one specific workflow, for example a script that files tasks from a CI job. That avoids the MCP layer entirely and is far less to maintain, but it is bespoke and does not give an interactive agent a general toolkit. The honest framing is that Feishu-MCP is the general-purpose option, and general-purpose here means a larger credential surface and a longer list of tools the agent can choose from, including destructive ones.

Maintenance cost and what the MIT licence does not cover

The repository is MIT licensed, which governs the code. It does not govern your Feishu tenant. The permissions you grant the app, the data the agent reads and writes, and any compliance obligations attached to that data sit with you and your Feishu administrator, not with the project. On maintenance, the release cadence visible in the material is uneven: 0.1.9 in January 2026, 0.2.2 in March, 0.2.3 in March, with the last push to the default branch in August 2026. The changelog is unusually candid, including a line where a planned Cursor login feature was abandoned with the note that it was unnecessary. That kind of entry is a good sign for a small project, since it means the roadmap is being edited rather than padded. The practical upgrade cost is low if you run via npx feishu-mcp@latest, because you get the newest version on every start, which is also the risk: an unattended client picks up behaviour changes without a version pin. Pinning a specific version in your client configuration is the cheaper habit. Upgrading across the 0.1.x to 0.2.x line is where to expect friction, since that range contains the scope validation default, the cache directory move and the Tool API refactor.

Editorial conclusion

Adopt Feishu-MCP if your documents and tasks already live in Feishu and you want an agent to edit them in place rather than pasting content back and forth. Skip it if you only need to read exported Markdown, or if you cannot get a Feishu app approved with the scopes the tool validates on startup. Before wiring it into a client, verify three things: that your app has been added to the target documents and folders, that FEISHU_AUTH_TYPE is set to user if you need task and user tools, and whether FEISHU_SCOPE_VALIDATION should stay at its default.

Official sources

1. cso1z/Feishu-MCP on GitHub
2. Issues
3. License: MIT
4. README
5. Releases