Feishu/Lark OpenAPI MCP

English | 中文

⚠️ Beta Version Notice: This tool is currently in Beta stage. Features and APIs may change, so please stay updated with version releases.

This is the Feishu/Lark official OpenAPI MCP (Model Context Protocol) tool designed to help users quickly connect to the Feishu/Lark platform and enable efficient collaboration between AI Agents and Feishu/Lark. The tool encapsulates Feishu/Lark Open Platform API interfaces as MCP tools, allowing AI assistants to directly call these interfaces and implement various automation scenarios such as document processing, conversation management, calendar scheduling, and more.

Features

Complete Feishu/Lark API Toolkit: Encapsulates almost all Feishu/Lark API interfaces, including message management, group management, document operations, calendar events, Bitable, and other core functional areas.
Dual Authentication Support:
- Supports App Access Token authentication
- Supports User Access Token authentication
Flexible Communication Protocols:
- Supports standard input/output stream (stdio) mode, suitable for integration with AI tools like Cursor/Claude
- Supports Server-Sent Events (SSE) mode, providing HTTP-based interfaces
Supports multiple configuration methods, adapting to different usage scenarios

Tool List

A complete list of all supported Feishu/Lark tools can be found in tools.md, where tools are categorized by project and version with descriptions.

Preparation

Creating a Feishu/Lark Application

Before using the lark-mcp tool, you need to create a Feishu/Lark application:

Visit the Feishu Open Platform or Lark Open Platform and log in
Click "Get Started" and create a new application
Obtain the App ID and App Secret, which will be used for API authentication
Add the necessary permissions for your application based on your usage scenario
If you need to call APIs as a user, set up OAuth 2.0 redirect URLs and obtain user access tokens

For detailed application creation and configuration guidelines, please refer to the Feishu Open Platform Documentation - Creating an Application or the Lark Open Platform Documentation.

Installing Node.js

Before using the lark-mcp tool, you need to install the Node.js environment.

Installing Node.js on macOS

Using Homebrew (Recommended):
```
brew install node
```
Using the Official Installer:
- Visit the Node.js website
- Download and install the LTS version
- After installation, verify in the terminal:
```
node -v
npm -v
```

Installing Node.js on Windows

Using the Official Installer:
- Visit the Node.js website
- Download and run the Windows installer (.msi file)
- Follow the installation wizard to complete the installation
- After installation, verify in the command prompt:
```
node -v
npm -v
```
Using nvm-windows:
- Download nvm-windows
- Install nvm-windows
- Use nvm to install Node.js:
```
nvm install latest
nvm use <version_number>
```

Installation

Install the lark-mcp tool globally:

npm install -g @larksuiteoapi/lark-mcp

Usage Guide

Using with Cursor/Claude

To integrate Feishu/Lark functionality in AI tools like Cursor or Claude, add the following to your configuration file:

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

To access APIs with user identity, you can add a user access token:

{
  "mcpServers": {
    "lark-mcp": {
     "command": "npx",
      "args": [
        "-y",
        "@larksuiteoapi/lark-mcp",
        "mcp",
        "-a",
        "<your_app_id>",
        "-s",
        "<your_app_secret>",
        "-u",
        "<your_user_token>"
      ]
    }
  }
}

Advanced Configuration

Command Line Parameters

The lark-mcp tool provides various command line parameters for flexible MCP service configuration:

Parameter	Short	Description	Example
`--app-id`	`-a`	Feishu/Lark application App ID	`-a cli_xxxx`
`--app-secret`	`-s`	Feishu/Lark application App Secret	`-s xxxx`
`--domain`	`-d`	Feishu/Lark API domain, default is Feishu China version	`-d https://open.larksuite.com`
`--tools`	`-t`	List of API tools to enable, separated by commas	`-t im.v1.message.create,im.v1.chat.create`
`--tool-name-case`	`-c`	Tool name format, options are snake, camel, dot, or kebab, default is snake	`-c camel`
`--language`	`-l`	Tools language, options are zh or en, default is en	`-l zh`
`--user-access-token`	`-u`	User access token for calling APIs as a user	`-u u-xxxx`
`--mode`	`-m`	Transport mode, options are stdio or sse, default is stdio	`-m sse`
`--host`		Listening host in SSE mode, default is localhost	`--host 0.0.0.0`
`--port`	`-p`	Listening port in SSE mode, default is 3000	`-p 3000`
`--config`		Configuration file path, supports JSON format	`--config ./config.json`
`--version`	`-V`	Display version number	`-V`
`--help`	`-h`	Display help information	`-h`

Parameter Usage Examples

Basic Usage (using application identity):
```
lark-mcp mcp -a cli_xxxx -s yyyyy
```

Using User Identity:

lark-mcp mcp -a cli_xxxx -s yyyyy -u u-zzzz

Specifying Lark International Domain:

lark-mcp mcp -a cli_xxxx -s yyyyy -d https://open.larksuite.com

Enabling Only Specific API Tools:

lark-mcp mcp -a cli_xxxx -s yyyyy -t im.v1.chat.create,im.v1.message.create

Using SSE Mode with Specific Port and Host:

lark-mcp mcp -a cli_xxxx -s yyyyy -m sse --host 0.0.0.0 -p 3000

Setting Tools Language to Chinese:
```
lark-mcp mcp -a cli_xxxx -s yyyyy -l zh
```
Note: Setting the language to Chinese (-l zh) may consume more tokens. If you encounter token limit issues when integrating with large language models, consider using the default English setting (-l en).
Setting Tool Name Format to Camel Case:
```
lark-mcp mcp -a cli_xxxx -s yyyyy -c camel
```
Note: By setting the tool name format, you can change how tool names appear in the MCP. For example, im.v1.message.create in different formats:
- snake format (default): im_v1_message_create
- camel format: imV1MessageCreate
- kebab format: im-v1-message-create
- dot format: im.v1.message.create

Using Environment Variables Instead of Command Line Parameters:

# Set environment variables
export APP_ID=cli_xxxx
export APP_SECRET=yyyyy

# Start the service (no need to specify -a and -s parameters)
lark-mcp mcp

Using Configuration File

Besides command line parameters, you can also use a JSON format configuration file to set parameters:

lark-mcp mcp --config ./config.json

Configuration file example (config.json):

{
  "appId": "cli_xxxx",
  "appSecret": "xxxx",
  "domain": "https://open.feishu.cn",
  "tools": ["im.v1.message.create","im.v1.chat.create"],
  "toolNameCase": "snake",
  "language": "zh",
  "userAccessToken": "",
  "mode": "stdio",
  "host": "localhost",
  "port": "3000"
}

Note: Command line parameters have higher priority than configuration file. When using both command line parameters and configuration file, command line parameters will override corresponding settings in the configuration file.

Using User Access Token

If you need to call APIs as a specific user, you can do so by specifying a User Access Token:

lark-mcp mcp -a <your_app_id> -s <your_app_secret> -u <your_user_token>

User access tokens can be obtained through the Feishu Open Platform's authorization process or Lark Open Platform's authorization process, or you can use the API debugging console to obtain them. After using a user access token, API calls will be made with that user's identity.

Specifying Custom Domains

If you are using the Lark international version or a custom domain, you can specify it using the -d parameter:

# Lark international version
lark-mcp mcp -a <your_app_id> -s <your_app_secret> -d https://open.larksuite.com

# Custom domain (KA domain)
lark-mcp mcp -a <your_app_id> -s <your_app_secret> -d https://open.your-ka-domain.com

Transport Modes

lark-mcp supports two transport modes:

stdio mode (Default/Recommended): Suitable for integration with AI tools like Cursor or Claude, communicating through standard input/output streams.
```
lark-mcp mcp -a <your_app_id> -s <your_app_secret> -m stdio
```

SSE mode: Provides an HTTP interface based on Server-Sent Events, suitable for web applications or scenarios requiring network interfaces.

# Default listens only on localhost
lark-mcp mcp -a <your_app_id> -s <your_app_secret> -m sse -p 3000

# Listen on all network interfaces (allowing remote access)
lark-mcp mcp -a <your_app_id> -s <your_app_secret> -m sse --host 0.0.0.0 -p 3000

After startup, the SSE endpoint will be accessible at http://<host>:<port>/sse.

Enabling More APIs

By default, the MCP service enables common APIs. To enable other tools or only specific APIs, you can specify them using the -t parameter (separated by commas):

lark-mcp mcp -a <your_app_id> -s <your_app_secret> -t im.v1.message.create,im.v1.message.list,im.v1.chat.create

Default Supported API List

By default, the MCP service enables the following APIs:

Tool Name	Function Description
im.v1.chat.create	Create a group chat
im.v1.chat.list	Get group chat list
im.v1.chatMembers.get	Get group members
im.v1.message.create	Send messages
im.v1.message.list	Get message list
wiki.v2.space.getNode	Get Wiki node
wiki.v1.node.search	Search Wiki nodes
docx.v1.document.rawContent	Get document content
drive.v1.permissionMember.create	Add collaborator permissions
docx.builtin.import	Import documents
docx.builtin.search	Search documents
bitable.v1.app.create	Create Bitable
bitable.v1.appTable.create	Create Bitable data table
bitable.v1.appTable.list	Get Bitable data table list
bitable.v1.appTableField.list	Get Bitable data table field list
bitable.v1.appTableRecord.search	Search Bitable data table records
bitable.v1.appTableRecord.create	Create Bitable data table records
bitable.v1.appTableRecord.update	Update Bitable data table records
contact.v3.user.batchGetId	Batch get user IDs

FAQ

Issue: Unable to connect to Feishu/Lark API Solution: Check your network connection and ensure your APP_ID and APP_SECRET are correct. Verify that you can access the Feishu/Lark Open Platform API; you may need to configure a proxy.
Issue: Error when using user_access_token Solution: Check if the token has expired. user_access_token usually has a validity period of 2 hours and needs to be refreshed periodically. You can implement an automatic token refresh mechanism or use app_access_token instead.
Issue: Unable to call certain APIs after starting the MCP service, with insufficient permissions errors Solution: Check if your application has obtained the corresponding API permissions. Some APIs require additional high-level permissions, which can be configured in the Developer Console or Lark Developer Console. Ensure that permissions have been approved.
Issue: Image or file upload/download related API calls fail Solution: The current version does not support file and image upload/download functionality. These APIs will be supported in future versions.
Issue: Command line displays garbled characters in Windows environment Solution: Change the command line encoding to UTF-8 by executing chcp 65001 in the command prompt. If using PowerShell, you may need to change the terminal font or PowerShell configuration.
Issue: Permission errors during installation Solution: On macOS/Linux, use sudo npm install -g @larksuiteoapi/lark-mcp for installation, or modify the permissions of the npm global installation path. Windows users can try running the command prompt as administrator.
Issue: Token limit exceeded after starting the MCP service Solution: Try using -t to reduce the number of enabled APIs, or use a model that supports larger tokens (such as claude3.7).
Issue: Unable to connect or receive messages in SSE mode Solution: Check if the port is already in use and try changing to a different port. Ensure that the client is correctly connected to the SSE endpoint and is handling the event stream.

Feedback

Issues are welcome to help improve this tool. If you have any questions or suggestions, please raise them in the GitHub repository.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
docs		docs
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmrc		.npmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
README_ZH.md		README_ZH.md
package.json		package.json
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Feishu/Lark OpenAPI MCP

Features

Tool List

Preparation

Creating a Feishu/Lark Application

Installing Node.js

Installing Node.js on macOS

Installing Node.js on Windows

Installation

Usage Guide

Using with Cursor/Claude

Advanced Configuration

Command Line Parameters

Parameter Usage Examples

Using Configuration File

Using User Access Token

Specifying Custom Domains

Transport Modes

Enabling More APIs

Default Supported API List

FAQ

Related Links

Feedback

About

Releases

Packages

Languages

License

larksuite/lark-openapi-mcp

Folders and files

Latest commit

History

Repository files navigation

Feishu/Lark OpenAPI MCP

Features

Tool List

Preparation

Creating a Feishu/Lark Application

Installing Node.js

Installing Node.js on macOS

Installing Node.js on Windows

Installation

Usage Guide

Using with Cursor/Claude

Advanced Configuration

Command Line Parameters

Parameter Usage Examples

Using Configuration File

Using User Access Token

Specifying Custom Domains

Transport Modes

Enabling More APIs

Default Supported API List

FAQ

Related Links

Feedback

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages