Feishu (Lark) MCP server

Integrates with Feishu (Lark) to enable document retrieval, messaging, and collaborative features directly within workplace conversations through a TypeScript implementation that runs as either a CLI or HTTP server.
Back to servers
Setup instructions
Provider
cso1z
Release date
Mar 17, 2025
Language
TypeScript
Package
Stats
3.8K downloads
101 stars

This article guides you through setting up and using a Feishu (Lark) MCP server to integrate AI-powered coding tools with Feishu documents. The server implements the Model Context Protocol, enabling tools like Cursor, Windsurf, and Cline to access and manipulate Feishu documents.

Getting Started

Quick Setup Options

You can run the Feishu MCP server in three different ways:

Option 1: Using NPM

npx feishu-mcp@latest --feishu-app-id=<YOUR_FEISHU_APP_ID> --feishu-app-secret=<YOUR_FEISHU_APP_SECRET>

Option 2: Using Smithery Platform

Access the pre-deployed version at Smithery.ai

Option 3: Local Installation

  1. Clone the repository:

    git clone https://github.com/cso1z/Feishu-MCP.git
    cd Feishu-MCP
    
  2. Install dependencies:

    pnpm install
    
  3. Create environment configuration:

    # macOS/Linux
    cp .env.example .env
    
    # Windows
    copy .env.example .env
    
  4. Edit the .env file and add your Feishu credentials:

    FEISHU_APP_ID=cli_xxxxx
    FEISHU_APP_SECRET=xxxxx
    PORT=3333
    
  5. Start the server:

    pnpm run dev
    

Configuration

Environment Variables

Variable Required Description Default
FEISHU_APP_ID Feishu application ID -
FEISHU_APP_SECRET Feishu application secret -
PORT Server port 3333

Command Line Arguments

Argument Description Default
--port Server listening port 3333
--log-level Log level (debug/info/log/warn/error/none) info
--feishu-app-id Feishu application ID -
--feishu-app-secret Feishu application secret -
--feishu-base-url Feishu API base URL https://open.feishu.cn/open-apis
--cache-enabled Enable caching true
--cache-ttl Cache time-to-live in seconds 3600
--stdio Run in command mode -
--help Show help menu -
--version Show version -

Configuration for Cursor, Cline, etc.

{
  "mcpServers": {
    "feishu-mcp": {
      "command": "npx",
      "args": ["-y", "feishu-mcp", "--stdio"],
      "env": {
        "FEISHU_APP_ID": "<YOUR_FEISHU_APP_ID>",
        "FEISHU_APP_SECRET": "<YOUR_FEISHU_APP_SECRET>"
      }
    }
  },
   "feishu_local": {
      "url": "http://localhost:3333/sse"
   }
}

Feishu Configuration

Before using this tool, you must set up a Feishu application and obtain credentials. Follow the official tutorial to create a Feishu application and get the necessary credentials.

Features

The server supports a comprehensive set of document management features:

Document Management

  • Create new Feishu documents
  • Get document information and content
  • Retrieve document block structure
  • Access specific block content

Content Editing

  • Batch create multiple blocks
  • Update block text content
  • Create text, code, heading, and list blocks
  • Delete document blocks

Folder Management

  • Get root folder information
  • Retrieve folder file listings
  • Create new folders

Search & Utilities

  • Search documents
  • Convert Wiki links to document IDs
  • Access image resources
  • Retrieve whiteboard content

Text Styling

  • Text formatting (bold, italic, underline, strikethrough, inline code)
  • Text colors (gray, brown, orange, yellow, green, blue, purple)
  • Text alignment (left, center, right)
  • Heading levels (1-9)
  • Code blocks with syntax highlighting
  • Ordered and unordered lists
  • Image insertion
  • Mathematical formulas with LaTeX syntax

Usage Tips

Specifying Folders

When creating new documents, it's recommended to provide a Feishu folder token (either a specific folder or root folder) for better document management. To get a folder token, open the Feishu folder page and copy the token from the URL (the last string of characters in https://.../drive/folder/xxxxxxxxxxxxxxxxxxxxxx).

Image Upload

When running the MCP locally, you can use both local absolute paths and http/https network images. In a server environment, only network image links are supported.

Formula Usage

You can use LaTeX syntax for mathematical formulas within text blocks, such as 1+2=3, \frac{a}{b}, \sqrt{x}, etc. Multiple formulas and regular text can be combined in the same text block.

Troubleshooting

Permission Issues

  1. Verify that your application has the necessary document access permissions
  2. Confirm that the target document has been authorized for the application or its group
  3. Check that the application's published version's available scope includes the document owner

Permission Verification

  1. Get a token using the app_access_token API
  2. Use the token to verify document access with the Get Document Info API

Common Issues

  • Application not found: Check if the application is published with correct scope
  • Insufficient permissions: Refer to Cloud Document FAQs
  • Knowledge base access issues: Refer to Wiki FAQs

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "feishu-mcp" '{"command":"npx","args":["-y","feishu-mcp","--stdio"],"env":{"FEISHU_APP_ID":"<\u4f60\u7684\u98de\u4e66\u5e94\u7528ID>","FEISHU_APP_SECRET":"<\u4f60\u7684\u98de\u4e66\u5e94\u7528\u5bc6\u94a5>"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "feishu-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "feishu-mcp",
                "--stdio"
            ],
            "env": {
                "FEISHU_APP_ID": "<\u4f60\u7684\u98de\u4e66\u5e94\u7528ID>",
                "FEISHU_APP_SECRET": "<\u4f60\u7684\u98de\u4e66\u5e94\u7528\u5bc6\u94a5>"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "feishu-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "feishu-mcp",
                "--stdio"
            ],
            "env": {
                "FEISHU_APP_ID": "<\u4f60\u7684\u98de\u4e66\u5e94\u7528ID>",
                "FEISHU_APP_SECRET": "<\u4f60\u7684\u98de\u4e66\u5e94\u7528\u5bc6\u94a5>"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect

Want to 10x your AI skills?

Get a free account and learn to code + market your apps using AI (with or without vibes!).

Nah, maybe later