Feishu

Feishu MCP Server enables AI-enabled tools to access, edit, and structure Feishu documents through a Model Context Protocol server, improving how you retrieve and work with document content across folders, blocks, and rich text. It supports folder browsing, structured content reading, smart creation and editing, and fast search, helping you build more capable AI-assisted document workflows.

How to use

You interact with Feishu MCP Server through an MCP client to manage Feishu documents and related content. Use the server to browse folder structures, fetch documents and their blocks, read rich text with structural context, create and update documents or blocks in batch, and search across your Feishu documents. You can also import images, tables, diagrams, and boards to enrich content, and leverage smart editing to align documents with your writing goals.

How to install

Prerequisites: ensure you have Node.js and npm installed on your system. It is recommended to use a package manager you are comfortable with (for example npm or pnpm). You will also need access to a Feishu app with the appropriate credentials.

Option A: Quick start with NPM (stdio mode) Use this to run the MCP directly in stdio mode from the command line.

# Run the Feishu MCP in stdio mode via npx
npx feishu-mcp@latest --feishu-app-id=<你的飞书应用ID> --feishu-app-secret=<你的飞书应用密钥> --feishu-auth-type=<tenant/user>

Option B: Local run (recommended for development) Clone the repository, configure environment variables, and start the server locally.

# 1) Clone the repository
git clone https://github.com/cso1z/Feishu-MCP.git
cd Feishu-MCP

# 2) Copy the example environment file and edit it
cp .env.example .env

# 3) Edit .env with your Feishu credentials
# FEISHU_APP_ID=your_app_id
# FEISHU_APP_SECRET=your_app_secret
# PORT=3333
# FEISHU_AUTH_TYPE=tenant

# 4) Install dependencies
pnpm install

# 5) Start the service
pnpm run dev

Option C: Run with Docker Compose Use Docker Compose to start the server in a containerized environment.

docker-compose up -d

docker-compose logs -f

Additional configuration and runtime notes

You can run the Feishu MCP Server in multiple ways, including a remote HTTP-based MCP configuration or a local stdio-based MCP instance. The HTTP approach exposes an endpoint you can connect to, while the stdio approach runs as a local process that you can integrate with your development environment.

Configuration and runtime security

Environment variables used by the server include FEISHU_APP_ID, FEISHU_APP_SECRET, FEISHU_AUTH_TYPE, and FEISHU_USER_KEY for stdio mode. You can also enable or disable permission checks with FEISHU_SCOPE_VALIDATION and customize user binding with FEISHU_USER_KEY. When running in stdio mode, you provide the key to identify the user interacting with Feishu documents.

# Example environment setup in the project root
FEISHU_APP_ID=cli_xxxxx
FEISHU_APP_SECRET=xxxxx
PORT=3333
FEISHU_AUTH_TYPE=tenant
FEISHU_USER_KEY=<your_user_identifier>
# Optional
FEISHU_SCOPE_VALIDATION=true

Configuration examples

The following configuration shows how to wire the Feishu MCP server into a client configuration. It demonstrates both the HTTP and stdio approaches. Adapt the values to your environment.

{
  "mcpServers": {
    "feishu_mcp_http": {
      "name": "feishu_http",
      "type": "http",
      "url": "http://localhost:3333/sse?userKey=123456",
      "args": []
    },
    "feishu_mcp_stdio": {
      "name": "feishu_stdio",
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "feishu-mcp@latest", "--stdio"],
      "env": {
        "FEISHU_APP_ID": "<你的飞书应用ID>",
        "FEISHU_APP_SECRET": "<你的飞书应用密钥>",
        "FEISHU_AUTH_TYPE": "<tenant/user>",
        "FEISHU_USER_KEY": "<你的用户标识>"
      }
    }
  }
}

Usage tips and troubleshooting

• Use a dedicated Feishu folder token when creating new documents to efficiently locate and manage content. If unsure, ask the AI to locate the most suitable subfolder under your designated folder.

• For image uploads in local runs, you can specify local paths or HTTP/HTTPS image URLs. In server deployments, use image URLs to avoid large payloads.

• Prefer user-level authentication for richer permissions and better OpenAPI compatibility. When switching from tenant to user authentication, adjust your permissions accordingly and pass the userKey parameter to identify the user.

Developer notes and resources

Access to development and technical guidance is available through the project wiki, including architecture, core modules, authentication, API references, and best practices. You can explore topics such as MCP protocol details and implementation notes to deepen your understanding and contribution.

Support and community

If this server helps you, consider sharing appreciation through a quick star, reporting issues, suggesting features, and contributing improvements. Your feedback drives faster enhancements and better documentation.

Available tools

create_feishu_document

Create a new Feishu document from scratch.

get_feishu_document_info

Fetch basic document information to verify existence and permissions.

get_feishu_document_blocks

Retrieve the document block tree to understand structure.

batch_create_feishu_blocks

Batch create multiple content blocks for rapid document building.

update_feishu_block_text

Update the text content of a document block.

delete_feishu_document_blocks

Delete blocks to clean up or restructure a document.

get_feishu_folder_files

List files within a Feishu folder for navigation.

create_feishu_folder

Create a new folder to organize documents.

search_feishu_documents

Search documents to locate specific content quickly.

get_feishu_image_resource

Download image resources from documents.

get_feishu_whiteboard_content

Extract content from whiteboards (diagrams, mind maps, etc.).

create_feishu_table

Create and edit tables to present structured data.

upload_and_bind_image_to_block

Insert local or remote images into blocks.

mermaid_chart_insert

Insert Mermaid diagrams such as flowcharts and mind maps.

formula_support

Insert and render mathematical formulas within text blocks.