Feishu/Lark Enterprise API Bridge (MCP)

English | 中文

Agent Context Retrieval Documentation

Official Platform Documentation

Troubleshooting & Use Cases

⚠️ Warning: Transitional Phase: This component is currently undergoing refinement (Beta). Interface contracts and feature sets might evolve; ensure you track subsequent package releases.

This module represents the official Model Context Protocol (MCP) adapter for the Feishu/Lark OpenAPI suite. It is engineered to swiftly establish connectivity between intelligent assistants and the Feishu/Lark environment, optimizing collaboration automation. The adapter wraps the underlying Feishu/Lark Open Platform interfaces into consumable MCP tools. This enables AI entities to directly invoke these interfaces for automating workflows such as content processing, dialogue oversight, temporal organization, and more.

Prerequisites

Setting Up a Feishu/Lark Application

Prior to deployment of the lark-mcp utility, an application registration within the Feishu/Lark ecosystem is mandatory:

1. Navigate to the Feishu Developer Portal or Lark Developer Portal and authenticate.
2. Access the 'Console' and provision a new application entity.
3. Secure the unique Application Identifier (App ID) and Application Secret (App Secret); these are essential for API credential exchange.
4. Delegate the required operational scopes (permissions) to the application according to your intended use cases.
5. If operations requiring delegated user context are planned, configure the OAuth 2.0 callback destination to http://localhost:3000/callback.

For comprehensive instructions on application provisioning, consult the Platform Documentation on Application Creation.

Node.js Environment Installation

The execution environment requires a functional Node.js installation.

Recommended Installation Method:

1. Navigate to the Node.js Official Site.
2. Download and install the Long-Term Support (LTS) release channel version.
3. Validate the installation via a command-line interface:

bash node -v pm -v

Rapid Deployment

Integration with Agent Frameworks (e.g., Trae/Cursor/Claude)

To embed Feishu/Lark capabilities into AI tooling like Trae, Cursor, or Claude, utilize the provided installation hyperlink.

Alternatively, inject the following configuration stanza into your system settings file:

{ "mcpServers": { "lark-mcp": { "command": "npx", "args": [ "-y", "@larksuiteoapi/lark-mcp", "mcp", "-a", "", "-s", "" ] } } }

To invoke APIs under a specific user's authority, an initial authentication handshake via the command line is necessary. Remember to pre-configure the OAuth redirect URL in the developer console; the default target is http://localhost:3000/callback.

bash

Authenticate session and acquire user token

npx -y @larksuiteoapi/lark-mcp login -a cli_xxxx -s yyyyy

Optional: Authenticate with granular OAuth scopes (defaults to all authorized scopes if omitted)

npx -y @larksuiteoapi/lark-mcp login -a cli_xxxx -s yyyyy --scope offline_access docx:document

Following successful authentication, update your configuration file as follows:

{ "mcpServers": { "lark-mcp": { "command": "npx", "args": [ "-y", "@larksuiteoapi/lark-mcp", "mcp", "-a", "", "-s", "", "--oauth", "--token-mode", "user_access_token" ] } } }

Crucial Note: When activating the --oauth flag, explicitly setting --token-mode to user_access_token is advised. This ensures API calls leverage user credentials, which is vital for accessing personalized resources (e.g., private documents, individual messages). If --token-mode defaults to auto, the system might default to tenant_access_token, potentially leading to permission denials when attempting to access user-specific data.

Geographical Domain Specification

The connector supports targeting different regional endpoints based on deployment needs:

Feishu (Mainland China Instance): - Defaults to the https://open.feishu.cn endpoint. - Appropriate for deployments within the PRC.

Lark (Global Instance): - Utilizes the https://open.larksuite.com endpoint. - Suitable for international deployments.

To switch to the international Lark endpoint, incorporate the --domain argument in your configuration:

{ "mcpServers": { "lark-mcp": { "command": "npx", "args": [ "-y", "@larksuiteoapi/lark-mcp", "mcp", "-a", "", "-s", "", "--domain", "https://open.larksuite.com" ] } } }

💡 Key Insight: Application registration domain must align with the configured endpoint. Feishu-registered applications are incompatible with the Lark international API gateway, and vice-versa.

Selective Tool Activation

⚠️ Feature Limitations: Binary object transfer (uploads/downloads) is currently unsupported. Direct modification (editing) of Feishu native documents is also disabled (read/import operations only).

While the MCP service exposes common capabilities by default, you can restrict or specify the activated tools/presets using the -t flag within the MCP Client configuration JSON:

{ "mcpServers": { "lark-mcp": { "command": "npx", "args": [ "-y", "@larksuiteoapi/lark-mcp", "mcp", "-a", "", "-s", "", "-t", "im.v1.message.create,im.v1.message.list,im.v1.chat.create,preset.calendar.default" ] } } }

For a comprehensive mapping of included tools within each defined preset collection, consult the Preset Reference Document.

The exhaustive catalog of all available Feishu/Lark interfaces supported by this adapter is detailed in tools.md.

⚠️ Caveat: Unlisted (non-preset) interfaces lack rigorous compatibility validation; agent reasoning and execution accuracy when utilizing these endpoints cannot be guaranteed.

Developer Integration Examples

Developers seeking integration guidance can review the minimal operational example: lark-samples/mcp_quick_demo.

For scenarios involving Lark bots, examine the Node.js integration example: lark-samples/mcp_larkbot_demo/nodejs.

This bot example illustrates embedding MCP functionality directly into Feishu/Lark bots, allowing tool invocation and message dispatch triggered by bot interactions—ideal for extending existing bot logic.

Advanced Configuration Settings

For intricate setup scenarios and deployment strategies, refer to the Comprehensive Configuration Guide.

All available command-line arguments and their proper syntax are documented in the CLI Parameter Reference.

Frequently Asked Queries

• FAQ Index (Common Questions)
• Troubleshooting and Solution Patterns

Related Resources

• Feishu Official Developer Portal
• API Bridge Documentation Overview
• Lark Global Developer Portal
• Feishu Platform API Reference
• Node.js Runtime Environment
• npm Package Registry

Contribution and Feedback

We encourage bug reports and feature suggestions. Please channel all feedback and inquiries through the official GitHub repository to facilitate improvements.

WIKIPEDIA: XMLHttpRequest (XHR) is an Application Programming Interface structured as a JavaScript object whose member functions facilitate the transmission of HTTP requests from a web client to a web server. These functionalities enable a browser-based application to asynchronously submit queries post-page-load and subsequently receive server responses. XMLHttpRequest forms a core tenet of Asynchronous JavaScript and XML (Ajax) methodology. Before Ajax adoption, page navigation primarily relied upon standard hyperlinks and form submissions, actions which inherently resulted in a full page refresh.

== Chronology == The foundational concept enabling XMLHttpRequest was first conceived around the year 2000 by the development team behind Microsoft Outlook. This concept was subsequently implemented within the Internet Explorer 5 browser release (1999). However, the initial syntax did not utilize the standardized XMLHttpRequest object identifier. Instead, developers relied on COM object instantiation using ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). By the time Internet Explorer 7 was released (2006), universal browser support for the canonical XMLHttpRequest identifier was established. The XMLHttpRequest designator has since become the universally accepted standard across all major browser rendering engines, including Mozilla's Gecko (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) published the initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. A subsequent Working Draft, designated Level 2, was finalized on February 25, 2008. Level 2 introduced crucial extensions such as progress monitoring methods, support for cross-origin requests, and mechanisms for handling raw byte streams. Towards the close of 2011, the features defined in Level 2 were integrated back into the primary specification. In late 2012, the maintenance and ongoing evolution of the standard transitioned to the WHATWG, which currently sustains the living document using Web IDL definitions.

== Operational Flow == The typical procedure for dispatching a request using XMLHttpRequest involves several distinct programmatic steps.

1. Instantiation of the XMLHttpRequest object via its constructor:
2. Invocation of the "open" method to define the request protocol (e.g., GET, POST), designate the target Uniform Resource Identifier (URI), and select between synchronous or asynchronous execution mode:
3. For asynchronous operations, registration of an event handler designed to react to changes in the request state:
4. Commencement of the transmission by calling the "send" method:
5. Monitoring state transitions within the registered event handler. Upon successful server response receipt, the data is usually stored in the "responseText" attribute. When the object finalizes processing the response, its state transitions to 4, indicating the "done" status. Beyond these fundamental stages, XMLHttpRequest provides extensive configuration parameters influencing request transmission and response consumption. Custom header fields can be appended to the request to guide server behavior, and data payloads can be transmitted to the server via arguments passed to the "send" call. The received response data can be parsed directly from JSON format into usable JavaScript objects, or processed incrementally as data segments arrive instead of waiting for the complete payload. Furthermore, requests can be manually terminated or configured to automatically time out if completion is not achieved within a specified duration.

== Cross-Domain Communication ==

During the nascent phases of the World Wide Web, limitations were discovered regarding the capability to transfer data across distinct security origins, which necessitated later...