Content
# Feishu MCP Server
[](https://www.npmjs.com/package/feishu-mcp)
[](https://smithery.ai/server/@cso1z/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, based on the [Model Context Protocol](https://modelcontextprotocol.io/introduction) server implementation.
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 searching.
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 batches 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 effects and operation process of MCP through the following video:
<a href="https://www.bilibili.com/video/BV1z7MdzoEfu/?vd_source=94c14da5a71aeb01f665f159dd3d89c8">
<img src="image/demo.png" alt="Feishu MCP Usage Demonstration" width="800"/>
</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 continue using it efficiently. Your support will also help us improve and develop the project better.⭐
---
## 🛠️ Tool Function Details
| Function Category | Tool Name | Description | Usage Scenario | Status |
|-------------------|---------------------------------------------------------------|----------------------------|-------------------------|--------|
| **Document Management** | `create_feishu_document` | Create a new Feishu document | Create documents from scratch | ✅ Completed |
| | `get_feishu_document_info` | Get basic document information | Verify document existence and permissions | ✅ Completed |
| | `get_feishu_document_blocks` | Get document block structure | Understand 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 folder file list | Browse folder content | ✅ 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` | Wiki link conversion | Convert Wiki link to document ID | ✅ Completed |
| | `get_feishu_image_resource` | Get image resources | Download images from documents | ✅ Completed |
| | `get_feishu_whiteboard_content` | Get whiteboard content | Retrieve graphic elements and structure from the whiteboard (flowcharts, mind maps, etc.) | ✅ Completed |
| **Advanced Features** | Table Operations | Create and edit tables | Structured data presentation | 🚧 Planned |
| | Chart Insertion | Support various data visualization charts | Data presentation and analysis | 🚧 Planned |
| | Flowchart Insertion | Support flowcharts and mind maps | Process organization and visualization | 🚧 Planned |
| Image Insertion | `upload_and_bind_image_to_block` | Support inserting local and remote images | Modify document content | ✅ Completed |
| | Formula Support | Support mathematical formulas | Academic and technical documents | ✅ Completed |
### 🎨 Supported Style Features
- **Text Styles**: Bold, Italic, Underline, Strikethrough, Inline Code
- **Text Colors**: Gray, Brown, Orange, Yellow, Green, Blue, Purple
- **Alignment**: Left, Center, Right
- **Heading Levels**: Supports headings from level 1 to 9
- **Code Blocks**: Supports syntax highlighting for various programming languages
- **Lists**: Ordered lists (numbered), Unordered lists (bulleted)
- **Images**: Supports local and online images
- **Formulas**: Insert mathematical formulas in text blocks, supports LaTeX syntax
---
## 📈 Weekly Plan: Enhance Tool Efficiency
- ~~**Streamline Toolset**: 21 tools → 13 tools, remove redundancy, focus on core functions~~ 0.0.15 ✅
- ~~**Optimize Descriptions**: 7000+ tokens → 3000+ tokens, simplify prompts, save request tokens~~ 0.0.15 ✅
- ~~**Batch Enhancements**: New batch updates, batch image uploads, 50% efficiency improvement for single operations~~ 0.0.15 ✅
- **Process Optimization**: Reduce multi-step calls to achieve one-click completion of complex tasks
- ~~**Support Multiple Credential Types**: Including tenant_access_token and user_access_token, meet authentication needs in different scenarios~~ (Feishu application configuration changes) 0.0.16 ✅.
---
## 🔧 Feishu Configuration Tutorial
**⚠️ Important Note: You must complete the Feishu application configuration before using this tool, or it 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 detailed guide on registering a Feishu application, configuring permissions, and adding document access permissions, please refer to [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>
```
### Method 2: Use Smithery Platform
**Published on Smithery platform, accessible at:** https://smithery.ai/server/@cso1z/feishu-mcp
### Method 3: Run Locally
#### 🌿 Branch Explanation
This project adopts a main branch (main) + feature branches (feature/xxx) collaboration model:
- **main**
Stable main branch, always kept in a usable and deployable state. All verified and officially released features will be merged into the main branch.
- **multi-user-token**
Development branch for multi-user isolation and user-authorized Feishu Token retrieval features. This branch supports userKey parameters, user-based token retrieval and caching, custom token services, etc., suitable for development and testing scenarios requiring multi-user isolation and authorization.
> ⚠️ This branch is in beta version, and feature updates may be delayed compared to the main branch. If you have related needs, please leave a message in the issue section, and I will prioritize syncing the latest features to this branch.
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)**
**macOS/Linux:**
```bash
cp .env.example .env
```
**Windows:**
```cmd
copy .env.example .env
```
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
```
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, recommended to use `user` (user-level, requires OAuth authorization) for local runs, and `tenant` (application-level, default) for cloud/production environments | `tenant` |
| `FEISHU_TOKEN_ENDPOINT` | ❌ | Token retrieval endpoint, only needed when custom token management is implemented | `http://localhost:3333/getToken` |
> **Note:**
> - The `user` credential is only supported when running the service locally; otherwise, you need to configure `FEISHU_TOKEN_ENDPOINT` to implement token retrieval and management yourself (refer to `callbackService`, `feishuAuthService`).
> - `FEISHU_TOKEN_ENDPOINT` interface parameters: `client_id`, `client_secret`, `token_type` (optional, tenant/user); return parameters: `access_token`, `needAuth`, `url` (when authorization is needed), `expires_in` (in seconds).
### Command Line Parameters
| Parameter | Description | Default Value |
|-----------|-------------|---------------|
| `--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` | Base URL for Feishu API | `https://open.feishu.cn/open-apis` |
| `--cache-enabled` | Whether to enable caching | `true` |
| `--cache-ttl` | Cache time-to-live (seconds) | `3600` |
| `--stdio` | Run in command mode | - |
| `--help` | Show help menu | - |
| `--version` | Show version number | - |
### Configuration File Method (Applicable for 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_local": {
"url": "http://localhost:3333/sse"
}
}
}
```
---
## 📝 Usage Tips (Important)
1. ### **Recommended to Specify Folder**:
When creating a new document, it is advisable to actively provide the Feishu folder token (which can be for 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 folder you specify to create the document.
> **How to Obtain 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 Explanation**:
When running MCP locally, the image path supports both local absolute paths and http/https network images; in server environments, only network image links are supported (due to cursor's parameter length limitation when calling mcp, direct uploading of image files is not supported at this time; please use image paths or links for uploads).
3. ### **Formula Usage Instructions**:
You can mix normal text and formula elements in text blocks. Formulas use LaTeX syntax, such as: `1+2=3`, `\frac{a}{b}`, `\sqrt{x}`, etc. It supports including multiple formulas and normal text within the same text block.
---
## 🚨 Troubleshooting
### Permission Issues
First, check against configuration issues: [Step-by-Step Tutorial FEISHU_CONFIG.md](FEISHU_CONFIG.md).
#### Problem Confirmation
1. **Check Application Permissions**: Ensure the application has obtained the necessary document access permissions.
2. **Verify Document Authorization**: Confirm that the target document has been authorized for the application or the group the application belongs to.
3. **Check Availability Scope**: Ensure the available scope of the application release version includes the document owner.
#### Permission Verification and Troubleshooting
1. Obtain token: [Self-built application to get app_access_token](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 whether you have permission to access the document: [Get Basic Document Information](https://open.feishu.cn/api-explorer?apiName=get&project=docx&resource=document&version=v1)
### Common Issues
- **Application Not Found**: Check if the application has been published and the availability scope is configured correctly.
- **Insufficient Permissions**: Refer to [Common Issues with Cloud Documents](https://open.feishu.cn/document/ukTMukTMukTM/uczNzUjL3czM14yN3MTN).
- **Knowledge Base Access Issues**: Refer to [Common Issues with Knowledge Base](https://open.feishu.cn/document/server-docs/docs/wiki-v2/wiki-qa).
---
## 💖 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)
