Feishu (Lark) MCP server

This MCP server allows AI coding tools like Cursor, Windsurf, and Cline to access and interact with Feishu documents through the Model Context Protocol. It provides comprehensive functionality for managing, editing, and searching Feishu documents, significantly enhancing document processing efficiency.

Installation Options

Quick Start with NPM

Run the server directly using npx:

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

Using Smithery Platform

Access the hosted version at: https://smithery.ai/server/@cso1z/feishu-mcp

Local Installation

1. Clone the repository

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

2. Install dependencies

   pnpm install
   

3. Set up environment variables

   For macOS/Linux:

   cp .env.example .env
   

   For Windows:

   copy .env.example .env
   

4. Edit the .env file with your Feishu credentials:

   FEISHU_APP_ID=cli_xxxxx
   FEISHU_APP_SECRET=xxxxx
   PORT=3333
   

5. Start the server

   pnpm run dev
   

Feishu Configuration

⚠️ Important: You must configure a Feishu application before using this tool.

For detailed instructions on creating a Feishu app and obtaining credentials, refer to the official tutorial.

Server Configuration

Environment Variables

Variable	Required	Description	Default
FEISHU_APP_ID	✅	Feishu app ID	-
FEISHU_APP_SECRET	✅	Feishu app 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 app ID	-
--feishu-app-secret	Feishu app secret	-
--feishu-base-url	Feishu API base URL	https://open.feishu.cn/open-apis
--cache-enabled	Enable caching	true
--cache-ttl	Cache TTL in seconds	3600
--stdio	Run in command mode	-
--help	Show help menu	-
--version	Show version	-

Configuration for AI Tools (Cursor, Cline, etc.)

Add this to your AI tool's configuration file:

{
  "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"
   }
}

Available Features

Document Management

• Create new Feishu documents
• Get document information
• Get document content (plain text)
• Get document block structure
• Get 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
• Get folder file list
• Create new folders

Search and Utilities

• Search documents
• Convert Wiki links to document IDs
• Get image resources

Supported Text Styles

• Text formatting: bold, italic, underline, strikethrough, inline code
• Text colors: gray, brown, orange, yellow, green, blue, purple
• Alignment: left, center, right
• Heading levels: 1-9
• Code blocks with syntax highlighting
• Ordered and unordered lists

Troubleshooting

Permission Issues

Verification Steps

1. Check app permissions: Ensure your app has the necessary document access permissions
2. Verify document authorization: Confirm the target document is authorized for your app
3. Check availability scope: Ensure the app's release version scope includes the document owner

Permission Validation

1. Obtain a token using the app_access_token API
2. Verify document access using the document info API

Common Issues

• App not found: Check if the app is published with correct availability scope
• Insufficient permissions: Review the cloud document FAQ
• Knowledge base access issues: See the wiki FAQ

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