Feishu-MCP

# Feishu MCP Server [](https://www.npmjs.com/package/feishu-mcp) [](./LICENSE) Provides the capability to access, edit, and structure Feishu documents for AI-driven coding tools such as [Cursor](https://cursor.sh/), [Windsurf](https://codeium.com/windsurf), [Cline](https://cline.bot/), and others, implemented based on the [Model Context Protocol](https://modelcontextprotocol.io/introduction) server. This project enables AI coding tools to directly access and understand the structured content of Feishu documents, significantly enhancing the intelligence and efficiency of document processing. **Completely covers the real usage flow of Feishu documents, helping you efficiently utilize document resources:** 1. **Folder Directory Access**: Quickly obtain and browse all documents under a Feishu document folder for overall management and search convenience. 2. **Content Retrieval and Understanding**: Supports multi-dimensional content reading including structured, chunked, and rich text, allowing AI to accurately understand the document context. 3. **Intelligent Creation and Editing**: Automatically create new documents, generate and edit content in bulk to meet diverse writing needs. 4. **Efficient Retrieval and Search**: Built-in keyword search helps you quickly find target information among a large number of documents. This project allows you to achieve intelligent retrieval, editing, and searching in your daily use of Feishu documents, enhancing content processing efficiency and experience. ### 🎬 Usage Demonstration Video You can learn about the actual usage and operation process of MCP through the following videos: <a href="https://www.bilibili.com/video/BV1z7MdzoEfu/?vd_source=94c14da5a71aeb01f665f159dd3d89c8"> <img src="image/demo.png" alt="Feishu MCP Usage Demonstration" width="300"/> </a> <a href="https://www.bilibili.com/video/BV18z3gzdE1w/?vd_source=94c14da5a71aeb01f665f159dd3d89c8"> <img src="image/demo_1.png" alt="Feishu MCP Usage Demonstration" width="300"/> </a> > ⭐ **Star this project to get the latest features and important updates first!** Following the project ensures you won't miss any new features, fixes, and optimizations, helping you to use it efficiently. Your support will also help us improve and develop the project better.⭐ --- ## 🛠️ Tool Function Details | Function Category | Tool Name | Description | Use Case | Status | |-------------------|---------------------------------------------------------------|----------------------|-------------------|----------| | **Document Management** | `create_feishu_document` | Create a new Feishu document | Create a document from scratch | ✅ Completed | | | `get_feishu_document_info` | Get basic information of the document | Verify document existence and permissions | ✅ Completed | | | `get_feishu_document_blocks` | Get the block structure of the document | Understand the document hierarchy | ✅ Completed | | **Content Editing** | `batch_create_feishu_blocks` | Batch create multiple blocks | Efficiently create continuous content | ✅ Completed | | | `update_feishu_block_text` | Update block text content | Modify existing content | ✅ Completed | | | `delete_feishu_document_blocks` | Delete document blocks | Clean up and restructure document content | ✅ Completed | | **Folder Management** | `get_feishu_folder_files` | Get the list of files in a folder | Browse folder contents | ✅ Completed | | | `create_feishu_folder` | Create a new folder | Organize document structure | ✅ Completed | | **Search Functionality** | `search_feishu_documents` | Search documents | Find specific content | ✅ Completed | | **Tool Functions** | `convert_feishu_wiki_to_document_id` | Convert Wiki link | Convert Wiki link to document ID | ✅ Completed | | | `get_feishu_image_resource` | Get image resources | Download images from the document | ✅ Completed | | | `get_feishu_whiteboard_content` | Get whiteboard content | Retrieve graphic elements and structure from the whiteboard (flowcharts, mind maps, etc.) | ✅ Completed | | **Advanced Features** | `create_feishu_table` | Create and edit tables | Structured data presentation | ✅ Completed | | | Flowchart Insertion | Support for flowcharts and mind maps | Process organization and visualization | ✅ Completed | | Image Insertion | `upload_and_bind_image_to_block` | Support for inserting local and remote images | Modify document content | ✅ Completed | | | Formula Support | Support for mathematical formulas | Academic and technical documents | ✅ Completed | ### 🎨 Supported Style Features (Basic support for all md formats) - **Text Styles**: Bold, Italic, Underline, Strikethrough, Inline Code - **Text Colors**: Gray, Brown, Orange, Yellow, Green, Blue, Purple - **Alignment**: Left Align, Center, Right Align - **Heading Levels**: Supports headings from level 1 to level 9 - **Code Blocks**: Supports syntax highlighting for multiple programming languages - **Lists**: Ordered Lists (Numbered), Unordered Lists (Bulleted) - **Images**: Supports local images and online images - **Formulas**: Insert mathematical formulas in text blocks, supports LaTeX syntax - **Mermaid Charts**: Supports flowcharts, sequence diagrams, mind maps, class diagrams, pie charts, etc. - **Tables**: Supports creating multi-row tables, cells can contain text, headings, lists, code blocks, and various content types ## 📈 Weekly Plan: Enhance Tool Efficiency - ~~**Streamline Toolset**: 21 tools → 13 tools, remove redundancy, focus on core functionalities~~ 0.0.15 ✅ - ~~**Optimize Descriptions**: 7000+ tokens → 3000+ tokens, simplify prompts, save request tokens~~ 0.0.15 ✅ - ~~**Batch Enhancements**: Added batch updates and batch image uploads, improving single operation efficiency by 50%~~ 0.0.15 ✅ - **Process Optimization**: Reduce multi-step calls to achieve complex tasks with one-click completion - ~~**Support Multiple Credential Types**: Including tenant_access_token and user_access_token, to meet authentication needs in different scenarios~~ (Changes in Feishu application configuration) 0.0.16 ✅. - ~~**Support Cursor User Login**: Convenient for user authentication on the cursor platform Not needed, unnecessary ❌~~ - ~~**Support Mermaid Charts**: Flowcharts, sequence diagrams, etc., enrich document content~~ 0.1.11 ✅ - ~~**Support Table Creation**: Create complex tables containing various block types, support style control~~ 0.1.2 ✅ - ~~**Support Multi-User User Authentication in Feishu**: One deployment can be used by multiple users~~ 0.1.3 ✅ - ~~**Support Automatic Refresh of user_access_token**: No need for frequent authorization, improving user experience~~ 0.1.6 ✅ --- ## 🔧 Feishu Configuration Tutorial **⚠️ Important Note: Before you start using this tool, you must complete the Feishu application configuration; otherwise, the tool will not function properly.** Instructions on how to create a Feishu application and obtain application credentials can be found in the [official tutorial](https://open.feishu.cn/document/home/develop-a-bot-in-5-minutes/create-an-app). **Detailed Feishu Application Configuration Steps**: For a comprehensive guide on registering a Feishu application, configuring permissions, and adding document access permissions, please refer to the [step-by-step tutorial FEISHU_CONFIG.md](FEISHU_CONFIG.md). --- ## 🏃‍♂️ Quick Start ### Method 1: Quick Run with NPM ```bash npx feishu-mcp@latest --feishu-app-id=<your Feishu app ID> --feishu-app-secret=<your Feishu app secret> --feishu-auth-type=<tenant/user> ``` ### Method 2: Run Locally 1. **Clone the repository** ```bash git clone https://github.com/cso1z/Feishu-MCP.git cd Feishu-MCP ``` 2. **Install dependencies** ```bash pnpm install ``` 3. **Configure environment variables (copy .env.example and save it as .env file)** 4. **Edit the .env file** Find and open the `.env` file in the project root directory with any text editor, and fill in your Feishu application credentials: ```env FEISHU_APP_ID=cli_xxxxx FEISHU_APP_SECRET=xxxxx PORT=3333 FEISHU_AUTH_TYPE=tenant/user ``` 5. **Run the server** ```bash pnpm run dev ``` ## ⚙️ Project Configuration ### Environment Variable Configuration | Variable Name | Required | Description | Default Value | |---------------|----------|----------------------------------------------------------------------|---------------| | `FEISHU_APP_ID` | ✅ | Feishu Application ID | - | | `FEISHU_APP_SECRET` | ✅ | Feishu Application Secret | - | | `PORT` | ❌ | Server Port | `3333` | | `FEISHU_AUTH_TYPE` | ❌ | Authentication Credential Type, use `user` (user-level, operates Feishu documents as the user's identity, requires OAuth authorization), use `tenant` (application-level, default) | `tenant` | ### Configuration File Method (Applicable to Cursor, Cline, etc.) ```json { "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_AUTH_TYPE": "<tenant/user>" } }, "feishu_local": { "url": "http://localhost:3333/sse?userKey=123456" } } } ``` ## 📝 Usage Tips (Important) 1. ### **Recommended Specifying Folder**: When creating a new document, it is advisable to actively provide the Feishu (飞书) folder token (which can be a specific folder or the root folder) to more efficiently locate and manage documents. If you are unsure about the specific subfolder, you can let the LLM automatically find the most suitable subdirectory under the specified folder to create the document. > **How to obtain the folder token?** > Open the Feishu folder page, copy the link (e.g., `https://.../drive/folder/xxxxxxxxxxxxxxxxxxxxxx`), and the token is the last string of characters in the link (e.g., `xxxxxxxxxxxxxxxxxxxxxx`, please do not disclose the real token). 2. ### **Image Upload Path Description**: When running MCP locally, the image path supports both local absolute paths and http/https network images; in a server environment, only network image links are supported (due to the parameter length limitation when calling MCP with cursor, direct uploading of image files is not currently supported, please use image paths or links for uploading). 3. ### **Formula Usage Instructions**: You can mix ordinary text and formula elements in a text block. Formulas use LaTeX syntax, such as: `1+2=3`, `\frac{a}{b}`, `\sqrt{x}`, etc. Multiple formulas and ordinary text can be included in the same text block. 4. ### **Using Feishu User Authentication**: User authentication and tenant authentication are differentiated when increasing permissions, so **it is important to pay attention to the configured permissions when switching from tenant to user for the first time**; to distinguish different users, you need to add a query parameter: userKey to the URL of the MCP server service, **this value is the unique identifier for the user, so it is best to make it as random as possible during setup**. ## 🚨 Troubleshooting ### Permission Issue Troubleshooting First, check against the configuration issues: [Step-by-step Guide FEISHU_CONFIG.md](FEISHU_CONFIG.md). #### Issue Confirmation 1. **Check Application Permissions**: Ensure that the application has obtained the necessary document access permissions. 2. **Verify Document Authorization**: Confirm that the target document is authorized for the application or the group to which the application belongs. 3. **Check Available Scope**: Ensure that the available scope of the application release version includes the document owner. #### Permission Verification and Troubleshooting 1. Obtain token: [Get app_access_token for self-built applications](https://open.feishu.cn/api-explorer?apiName=app_access_token_internal&project=auth&resource=auth&version=v3) 2. Use the token obtained in step 1 to verify if you have permission to access the document: [Get basic information of the document](https://open.feishu.cn/api-explorer?apiName=get&project=docx&resource=document&version=v1) ### Frequently Asked Questions - **Application Not Found**: Check if the application has been published and if the availability settings are configured correctly. - **Insufficient Permissions**: Refer to the [Common Issues with Cloud Documents](https://open.feishu.cn/document/ukTMukTMukTM/uczNzUjL3czM14yN3MTN). - **Knowledge Base Access Issues**: Refer to the [Common Issues with Knowledge Base](https://open.feishu.cn/document/server-docs/docs/wiki-v2/wiki-qa). ## 📚 Developer Wiki Detailed development documentation and technical guides provide comprehensive guidance for learners and contributors: - **[Wiki Home](https://github.com/cso1z/Feishu-MCP/wiki)** - Complete documentation index and quick navigation - **[Architecture Design](https://github.com/cso1z/Feishu-MCP/wiki/架构设计)** - Overview of the overall architecture and technology stack - **[Core Module Details](https://github.com/cso1z/Feishu-MCP/wiki/核心模块详解)** - Implementation details and code examples for each module - **[Authentication and Authorization](https://github.com/cso1z/Feishu-MCP/wiki/认证与授权机制)** - Token management and multi-user support mechanisms - **[Developer Guide](https://github.com/cso1z/Feishu-MCP/wiki/开发者指南)** - Environment setup, development process, debugging tips - **[API Reference](https://github.com/cso1z/Feishu-MCP/wiki/API-参考文档)** - Detailed documentation of all utility functions - **[Best Practices](https://github.com/cso1z/Feishu-MCP/wiki/最佳实践)** - Code standards, performance optimization, security practices - **[MCP Protocol Implementation](https://github.com/cso1z/Feishu-MCP/wiki/MCP-协议实现)** - Detailed explanation of the MCP protocol and transport layer implementation --- ## 💖 Support the Project If this project has helped you, please consider: - ⭐ Giving the project a Star - 🐛 Reporting Bugs and Issues - 💡 Suggesting New Features - 📖 Improving Documentation - 🔀 Submitting Pull Requests Your support is our motivation to move forward! ## Star History [](https://www.star-history.com/#cso1z/feishu-mcp&Timeline)