Feishu/Lark OpenAPI MCP

English | 中文

Developer Documentation Retrieval MCP

Official Document

Trouble Shooting

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

This repository is the ticoag/lark maintained MCP distribution for Feishu/Lark OpenAPI. It is forked from larksuite/lark-openapi-mcp and continues development in the monorepo at ticoag/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.

Preparation

Creating a Feishu/Lark Application

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

1. Visit the Feishu Open Platform or Lark Open Platform and log in
2. Click "Console" and create a new application
3. Obtain the App ID and App Secret, which will be used for API authentication
4. Add the necessary permissions for your application based on your usage scenario
5. If you need to call APIs as a user, set the OAuth 2.0 redirect URL to http://localhost:3000/callback

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

Installing Node.js

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

Using the Official Installer (Recommended):

1. Visit the Node.js website
2. Download and install the LTS version
3. After installation, verify in the terminal:

node -v
npm -v

Quick Start

Using with Trae/Cursor/Claude/Codex

To integrate Feishu/Lark functionality in AI tools like Trae, Cursor, Claude, or Codex, install using the button below or add the server manually in your client config.

or add the following to your configuration file:

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

If you are using Codex CLI / Codex App, add the MCP server to ~/.codex/config.toml:

[mcp_servers.lark]
command = "npx"
args = [
  "-y",
  "@ticoag/lark-mcp",
  "mcp",
  "-a",
  "<your_app_id>",
  "-s",
  "<your_app_secret>",
]

Notes:

• We recommend using lark as the server key so Codex exposes tools as mcp__lark__ls, mcp__lark__help, mcp__lark__run, and mcp__lark__explain
• If you use a different key, the Codex tool prefix will change accordingly
• Restart Codex or reload MCP config after editing ~/.codex/config.toml

If you need to access APIs with user identity, you need to login first using the login command in the terminal. Note that you need to configure the application's redirect URL in the developer console first, default is http://localhost:3000/callback

# Login and get user access token
npx -y @ticoag/lark-mcp login -a cli_xxxx -s yyyyy
   
# Or optionally, login with specific OAuth scope - if not specified, all permissions will be authorized by default
npx -y @ticoag/lark-mcp login -a cli_xxxx -s yyyyy --scope offline_access docx:document

Then add the following to your configuration file:

{
  "mcpServers": {
    "lark-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@ticoag/lark-mcp",
        "mcp",
        "-a",
        "<your_app_id>",
        "-s",
        "<your_app_secret>",
        "--oauth",
        "--token-mode", "user_access_token"
      ]
    }
  }
}

If you are using Codex, write the same OAuth arguments into ~/.codex/config.toml:

[mcp_servers.lark]
command = "npx"
args = [
  "-y",
  "@ticoag/lark-mcp",
  "mcp",
  "-a",
  "<your_app_id>",
  "-s",
  "<your_app_secret>",
  "--oauth",
  "--token-mode",
  "user_access_token",
]

Note: When enabling --oauth, it's recommended to explicitly set --token-mode to user_access_token, which means calling APIs with user access tokens, suitable for accessing user resources or scenarios requiring user authorization (such as reading personal documents, sending IM messages). If you keep the default auto, some APIs AI may fallback to tenant_access_token, which could result in insufficient permissions or inability to access user private data.

Domain Configuration

Based on your usage scenario, lark-mcp supports configuring different domain environments:

Feishu (China Version):

• Default uses https://open.feishu.cn domain
• Suitable for users in China

Lark (International Version):

• Uses https://open.larksuite.com domain
• Suitable for overseas users or international version of Lark

To switch to the international version of Lark, add the --domain parameter in your configuration:

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

💡 Tip: Ensure your application is created in the corresponding domain environment's open platform. International version applications cannot be used with Feishu China version, and vice versa.

Command Surface

Starting from this version, the public MCP surface defaults to a command-oriented facade instead of exposing the raw OpenAPI tools directly to the client.

The public surface now exposes 4 tools:

• ls: list available commands, resources, and actions
• help: inspect help for a node or argument
• run: execute a command
• explain: explain an error, permission, scope, or identity issue

The interaction model is:

• command
• resource
• action

Examples:

• doc document search
• drive folder create
• chat message create
• perm permission-member transfer-owner
• calendar calendar-event create
• task task create

Notes:

• Raw OpenAPI tools are still kept internally as the execution/mapping layer
• The default preset now includes representative actions for drive, perm, task, and calendar; use preset.doc.default, preset.task.default, or preset.calendar.default for deeper domain coverage
• Deprecated APIs marked by Feishu/Lark as Deprecated Version (Not Recommended) are filtered out by default; only APIs explicitly listed in --deprecated-tools are re-enabled
• -t/--tools now constrains the raw capabilities available behind the facade, rather than changing the public tool names seen by the client
• Results include cite metadata such as help_target, raw_tool, docs_url, and resource_url for bidirectional traceability

Migration:

• See the Command Surface Migration Guide for raw-to-facade mappings, breaking changes, and explain guidance

Custom API Configuration

⚠️ File Upload/Download: File upload and download operations are not yet supported

⚠️ Document Editing: Direct editing of Feishu cloud documents is not supported (only importing and reading are available)

By default, the MCP service enables all supported APIs in the current build. To limit the surface to specific tools or presets, you can specify them using the -t parameter in the MCP Client configuration (JSON):

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

For detailed information about all preset tool collections and which tools are included in each preset, please refer to the Preset Tool Collections Reference.

A complete list of all supported Feishu/Lark tools can be found in tools.md.

⚠️ Notice：Non-preset APIs have not undergone compatibility testing, and the AI may not perform optimally during the process of understanding and using them.

Development Integration

Developers can refer to the minimal example for integrating with Agent: lark-samples/mcp_quick_demo.

You can also refer to the Lark bot integration example: lark-samples/mcp_larkbot_demo/nodejs.

This example demonstrates how to integrate MCP capabilities into Feishu/Lark bots, triggering tool calls and message sending through bot conversations, suitable for scenarios that integrate existing tools into Bot.

Advanced Configuration

For detailed configuration options and deployment scenarios, please refer to our Configuration Guide.

For detailed information about all available command line parameters and their usage, please refer to the Command Line Reference.

Maintainer Release

The monorepo defines GitHub Actions workflows for CI and npm publishing:

• CI: ../.github/workflows/ci.yml
• npm publish: ../.github/workflows/publish-npm.yml
• Both workflows set NODE_OPTIONS=--max-old-space-size=4096 for the lark-openapi-mcp job so tsc does not hit the default Node heap limit on GitHub Actions

Release flow:

1. Update version in package.json and CHANGELOG.md
2. Run npm ci && npm run build && npm run test:ci && npm run pack:check
3. Push a git tag named lark-openapi-mcp-vX.Y.Z
4. Let GitHub Actions publish @ticoag/lark-mcp with npm publish --provenance --access public

The publish workflow uses npm trusted publishing for @ticoag/lark-mcp against the GitHub repository ticoag/lark and workflow .github/workflows/publish-npm.yml. On npmjs.com, configure the trusted publisher with the workflow filename publish-npm.yml (filename only, not the full path). CI and publish share the package validation logic through .github/workflows/lark-openapi-checks.yml; the publish job downloads the checked artifact, runs on Node 24, upgrades npm to the latest CLI, and then publishes via OIDC. If you need authentication for private dependencies, use a separate read-only token only for npm ci; npm publish itself should rely on OIDC.

FAQ

• FAQ (Frequently Asked Questions)
• Common Issues and Use Cases

Related Links

• Feishu Open Platform
• Development Documentation: OpenAPI MCP
• Lark International Open Platform
• Feishu Open Platform API Documentation
• Node.js Website
• npm Documentation

Feedback

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