Content
# Tool List
[](https://www.npmjs.com/package/feishu-mcp)
[](./LICENSE)
Provides access, editing, and structured processing capabilities for Feishu documents, tasks, and user information for AI-driven coding tools like [Cursor](https://cursor.sh/), [Windsurf](https://codeium.com/windsurf), and [Cline](https://cline.bot/), based on the [Model Context Protocol](https://modelcontextprotocol.io/introduction) server implementation.
**Supports `feishu-tool` independent CLI tool**, which allows direct invocation of all Feishu tools in terminals or scripts without starting the MCP server. Works with [Feishu-Skill](https://github.com/cso1z/Feishu-Skill) to enable AI Agents like Claude Code to automatically choose the most suitable method to operate Feishu.
This project enables AI coding tools to:
- **Document Processing**: Directly obtain, understand, create, and edit Feishu documents, significantly improving document processing intelligence and efficiency.
- **Task Management**: List, create, update, and delete Feishu tasks, supporting subtasks and member management (requires user authentication).
- **User Information**: Search for Feishu users by name or obtain users in batches by ID, facilitating task assignment and document collaboration (requires user authentication).
**Fully covers the real usage process of Feishu documents**, helping you efficiently utilize document resources:
1. **Folder directory acquisition**: Quickly obtain and browse Feishu document folders and their documents, facilitating overall management and search.
2. **Content acquisition and understanding**: Supports structured, block-based, and rich text multi-dimensional content reading, allowing AI to accurately understand document context.
3. **Intelligent creation and editing**: Automatically create new documents, generate and edit content in batches, meeting diverse writing needs.
4. **Efficient retrieval and search**: Built-in keyword search helps you quickly find target information in a large number of documents.
5. **Task management and user query**: Supports Feishu task CRUD and user information search, facilitating task association and personnel management in documents.
This project enables intelligent acquisition, editing, and search of Feishu documents, and extends task and user management capabilities, improving content processing efficiency and experience.
### 💡 Project Recommendations:
Use Claude Code with [claude-ip-guard](https://github.com/cso1z/claude-ip-guard) - automatically detect IP geolocation and intercept restricted area access to prevent Claude account blocking due to network changes.
### 🎬 Usage Demo Videos
You can understand the actual usage effects 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 Demo" width="300"/>
</a>
<a href="https://www.bilibili.com/video/BV18z3gzdE1w/?vd_source=94c14da5a71aeb01f665f159dd3d89c8">
<img src="image/demo_1.png" alt="Feishu MCP Usage Demo" width="300"/>
</a>
> ⭐ **Star this project** to get the latest features and important updates first! Follow the project to avoid missing any new features, fixes, and optimizations, and help you continue to use it efficiently. Your support will also help us better improve and develop the project. ⭐
## 🛠️ 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 document basic 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 and refactor 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 Function** | `search_feishu_documents` | Search documents | Find specific content | ✅ Completed |
| **Tool Function** | `get_feishu_document_info` | Get wiki document information | Convert Wiki link to document ID, create wiki sub-node | ✅ Completed |
| | `get_feishu_image_resource` | Get image resources | Download images in documents | ✅ Completed |
| | `get_feishu_whiteboard_content` | Get whiteboard content | Get graphical elements and structure (flowcharts, mind maps, etc.) | ✅ Completed |
| **Advanced Function** | `create_feishu_table` | Create and edit tables | Structured data display | ✅ Completed |
| | Insert flowchart | Support flowcharts and mind maps | Process combing and visualization | ✅ Completed |
| | Insert flowchart (whiteboard form) | Support flowcharts and mind maps | Process combing and visualization | ✅ Completed |
| 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 |
| | | | | |
| **Task Management** | `list_feishu_tasks` | List tasks I am responsible for | View pending/completed tasks | ✅ Completed |
| | `create_feishu_task` | Batch create tasks (including subtasks) | Create new tasks, split subtasks | ✅ Completed |
| | `update_feishu_task` | Update tasks | Modify content, members, reminders | ✅ Completed |
| | `delete_feishu_task` | Batch delete tasks | Clean up tasks | ✅ Completed |
| **User Information** | `get_feishu_users` | Search for users by name or get users in batches by ID | Find members, task assignment | ✅ Completed |
### 🎨 Supported Style Functions (Basic support for md all formats)
- **Text Style**: Bold, italic, underline, strikethrough, inline code
- **Text Color**: Gray, brown, orange, yellow, green, blue, purple
- **Alignment**: Left-aligned, centered, right-aligned
- **Title Level**: Support 1-9 level titles
- **Code Block**: Support multiple programming language syntax highlighting
- **List**: Ordered list (numbered), unordered list (project symbol)
- **Image**: Support local and network images
- **Formula**: Insert mathematical formulas in text blocks, support LaTeX syntax
- **Mermaid Chart**: Support flowcharts, timing diagrams, mind maps, class diagrams, pie charts, etc.
- **Table**: Support creating multi-line list tables, cells can contain text, titles, lists, code blocks, etc.
- **Feishu Document Whiteboard**: Support creating whiteboards in Feishu documents, providing richer and more diverse content.
---
## 📈 Weekly Plan: Improve Tool Efficiency
- ~~**Streamline toolset**: 21 tools → 13 tools, remove redundancy, focus on core functions ~~ 0.0.15 ✅
- ~~**Optimize description**: 7000+ tokens → 3000+ tokens, simplify prompts, save request tokens ~~ 0.0.15 ✅
- ~~**Batch enhancement**: Add batch update, batch image upload, single operation efficiency improved by 50% ~~ 0.0.15 ✅
- **Process optimization**: Reduce multi-step calls, achieve one-click completion of complex tasks
- ~~**Support multiple certificate types**: Including tenant_access_token and user_access_token, meet authentication needs in different scenarios ~~ (Feishu application configuration changes) 0.0.16 ✅
- ~~**Support cursor user login**：Convenient for cursor platform user authentication Not done, no need ❌~~
- ~~**Support mermaid chart**: Flowcharts, timing diagrams, etc., enrich document content ~~ 0.1.11 ✅
- ~~**Support table creation**: Create complex tables with various block types, support style control ~~ 0.1.2 ✅
- ~~**Support Feishu multi-user user authentication**: One person deployed, multiple people can use ~~ 0.1.3 ✅
- ~~**Support user_access_token automatic refresh**: No need to authorize frequently, improve user experience ~~ 0.1.6 ✅
- ~~**Support authorization range verification**: Verify application authorization to ensure it meets the requirements of the current tool. If the conditions are not met, provide friendly guidance for users to use smoothly ~~ 0.1.7 ✅
- ~~**Support creating whiteboard content**: Compared with Mermaid charts, whiteboards can display richer and more diverse content, providing a more friendly and pleasant visual experience ~~ (Feishu application configuration changes) 0.1.7 ✅
- **Extract environment variables feishuAppId and feishuAppSecret**: Separate Feishu configuration from environment variables for easy setting in clients like cursor.
- ~~**Support knowledge base and my document library**: Realize knowledge base, my document library node traversal, node creation, file creation, search, etc. ~~ (Feishu application configuration changes) 0.1.8 ✅
- **Version update notification**: Provide relevant prompts and instructions when releasing new versions.
- ~~**stdio mode user authentication issue**: Fix user authentication failure in stdio mode ~~ 0.1.9 ✅
- ~~**Permission check function configurable**: Make permission check a configurable option, support control through environment variable `FEISHU_SCOPE_VALIDATION` or command-line parameter `--feishu-scope-validation`, default enabled, meet different user scenarios ~~ 0.2.0 ✅
- ~~**Optimize cache directory: save token and other caches to system-level configuration directory ~~ 0.2.2 ✅ Thanks to [Molunerfinn](https://github.com/Molunerfinn), [leeeezx](https://github.com/leeeezx), [Master-cai](https://github.com/Master-cai) for suggestions and code contributions
- ~~**Optimize mcpTool related code**: Rebuild code structure to lay a foundation for adding more functions ~~ 0.2.3 ✅
- ~~**Support task management**: List, create, update, delete Feishu tasks, support subtasks and member management ~~ 0.2.4 ✅
- ~~**Support user information query**: Search for users by name or get users in batches by ID, facilitate task assignment and document collaboration ~~ 0.2.4 ✅
- ~~**Tool API layer extraction**: Create Tool API layer, corresponding to tool layer one-to-one, unified parameter verification, data conversion, error mapping, etc. ~~ ✅
- ~~**Compatible CLI mode**: Support `feishu-tool <tool-name> '<json>'` command-line invocation, convenient for scripts and automation scenarios ~~ 0.2.6 ✅
- ~~**Complete Skill**: Provide [Feishu-Skill](https://github.com/cso1z/Feishu-Skill), guide Claude Code and other AI Agents to use feishu-mcp CLI in suitable scenarios ~~ 0.2.6 ✅
---
## 🔧 Feishu Configuration Tutorial
**⚠️ Important hint: Before using, you must complete Feishu application configuration, otherwise, the tool cannot be used normally.**
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 Feishu applications, configuring permissions, and adding document access permissions, please refer to [Step-by-Step Tutorial FEISHU_CONFIG.md](FEISHU_CONFIG.md).
---
## 🏃♂️ Quick Start
### Method 1: Use NPM to Run Quickly
```bash
npx feishu-mcp@latest --feishu-app-id=<Your Feishu App ID> --feishu-app-secret=<Your Feishu App Secret> --feishu-auth-type=<tenant/user> --enabled-modules=<document,task>
```
### Method 2: Local Operation
1. **Clone the repository**
```bash
git clone https://github.com/cso1z/Feishu-MCP.git
cd Feishu-MCP
```
2. **Configure environment variables (copy a.env.example and save as .env file)**
3. **Edit .env file**
In the project root directory, find and open the `.env` file 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
FEISHU_ENABLED_MODULES=document,task
```
4. **Run the server**
Method 1: Local operation
- **Install dependencies**
```bash
pnpm install
```
- **Start service**
```bash
pnpm run dev
```
Method 2: Use Docker Compose
- **Start service**
```bash
docker-compose up -d
```
- **View logs**
```bash
docker-compose logs -f
```
---
## 🖥️ feishu-tool CLI Tool
From version `0.2.5`, the `feishu-mcp` npm package comes with `feishu-tool` independent CLI, which can directly invoke all Feishu tools in terminals, Shell scripts, or AI Agents without starting the MCP server.
### Installation
```bash
# Global installation (recommended)
npm install -g feishu-mcp@latest
```
### Configuration
```bash
# 1. View CLI overview (subcommands + available toolset)
feishu-tool --help
# 2. View initialization guide (steps to get App ID / Secret)
feishu-tool guide
# 3. Write credentials
feishu-tool config set FEISHU_APP_ID cli_xxxxx
# 4. View current configuration (confirm written correctly)
feishu-tool config
# 5. View detailed parameters of a tool
feishu-tool help create_feishu_document
# 6. Invoke tool
feishu-tool create_feishu_document '{"title": "Test Document"}'
```
> For complete parameter instructions, please refer to [Feishu-Skill documentation](https://github.com/cso1z/Feishu-Skill).
---
## ⚙️ Project Configuration
### Environment Variables Configuration
| Variable Name | Required | Description | Default Value |
|---------------|----------|--------------------------------------------------------------------|---------------|
| `FEISHU_APP_ID` | ✅ | Feishu App ID | - |
| `FEISHU_APP_SECRET` | ✅ | Feishu App Secret | - |
| `PORT` | ❌ | Server Port | `3333` |
| `FEISHU_BASE_URL` | ❌ | Feishu API Base URL, Lark International can be configured to `https://open.larksuite.com/open-apis` | `https://open.feishu.cn/open-apis` |
| `FEISHU_AUTH_BASE_URL` | ❌ | Feishu Authorization Page Domain, Lark International set to `https://accounts.larksuite.com` | `https://accounts.feishu.cn` |
| `FEISHU_PUBLIC_BASE_URL` | ❌ | Publicly accessible base URL for the service. If MCP accesses through an internal network address but OAuth callback requires a public domain name, it can be set to e.g., `https://mcp.example.com` | - |
| `FEISHU_AUTH_TYPE` | ❌ | Authentication credential type, using `user` (user-level, uses user's identity to operate Feishu documents, requires OAuth authorization), using `tenant` (application-level, default) | `tenant` |
| `FEISHU_SCOPE_VALIDATION` | ❌ | Whether to enable permission check, set to `false` to disable permission check (applicable to scenarios where only some functions are used) | `true` |
| `FEISHU_ENABLED_MODULES` | ❌ | Enabled modules: `document`, `task`, `calendar`, `member`, `all`. task/calendar/member require user authentication | `document` |
| `FEISHU_USER_KEY` | ❌ | User identifier in `stdio` mode, can be overridden by command-line parameter `--user-key` | `stdio` |
| `FEISHU_ENCRYPTION_KEY` | ❌ | Encryption key for sensitive fields in token cache. Any string, system automatically derives encryption key through SHA-256. After setting, sensitive fields like `access_token`, `refresh_token`, `client_secret` will be stored encrypted. It is recommended to set a fixed key when deploying with Docker | - |
### Function Module Description
| Module | Description | Authentication Requirements |
|--------|-------------|---------------------------|
| `document` | Documents, folders, search, etc. | tenant / user |
| `task` | Task CRUD | Only user |
| `calendar` | Calendar (under development) | Only user |
| `member` | User information query | Only user |
| `all` | Enable all modules | All loaded when user |
### Configuration File Method (Applicable to Cursor, Cline, etc.)
#### stdio Mode (Recommended)
```
{
"mcpServers": {
"feishu-mcp": {
"command": "npx",
"args": ["-y", "feishu-mcp@latest", "--stdio"],
"env": {
"FEISHU_APP_ID": "<Your Feishu App ID>",
"FEISHU_APP_SECRET": "<Your Feishu App Secret>",
"FEISHU_AUTH_TYPE": "<tenant/user>",
"FEISHU_ENABLED_MODULES": "document,task",
"FEISHU_USER_KEY": "<Your User Key>"
}
}
}
}
```
#### SSE Mode
```
{
"mcpServers": {
"feishu_local": {
"url": "http://localhost:3333/sse?userKey=123456"
}
}
}
```
#### HTTP Streamable Mode
```
{
"mcpServers": {
"feishu_streamable": {
"url": "http://localhost:3333/mcp?userKey=123456"
}
}
}
```
**⚠️ Important Note**: The `userKey` in the URL represents the user's identifier, which is a very important configuration. Please fill it in and make it as random as possible.
**userKey Passing Method**: Two methods are supported to pass the user identifier:
- **URL Query Parameter**: `?userKey=123456` (recommended, simple configuration)
- **Request Header**: `user-key: 123456` (suitable for scenarios where parameters need to be hidden)
---
## 📝 Usage Tips (Important)
1. ### **Recommended to Specify a Folder**:
When creating a new document, it is recommended to actively provide a Feishu folder token (can be a specific folder or root folder), which can more efficiently locate and manage documents. If the specific subfolder is not sure, you can let LLM automatically find the most suitable sub-directory under the specified folder to create a new document.
> **How to get the folder token?**
> Open the Feishu folder page, copy the link (e.g., `https://.../drive/folder/xxxxxxxxxxxxxxxxxxxxxx`), and the token is the string at the end of the link (e.g., `xxxxxxxxxxxxxxxxxxxxxx`, please do not leak the real token).
2. ### **Picture Upload Path Description**:
When running MCP locally, the picture path supports both local absolute path and http/https network pictures; if in a server environment, only network picture links are supported (due to the limitation of the parameter length when cursor calls MCP, it is not supported to directly upload the picture file body, please use the picture path or link method to upload).
3. ### **Formula Usage Description**:
Ordinary text and formula elements can be mixed in a text block. The formula uses LaTeX syntax, such as: `1+2=3`, `\frac{a}{b}`, `\sqrt{x}`, etc. It supports multiple formulas and ordinary text in the same text block.
4. ### **Using Feishu User Authentication**:
User authentication and tenant authentication have different permission distinctions, so **when switching from tenant to user for the first time, you need to pay attention to the configured permissions**; in order to distinguish different users, you need to pass the user identifier userKey, which supports two methods:
- **URL Query Parameter**: Add `?userKey=123456` to the MCP server URL
- **Request Header**: Pass `user-key: 123456` request header
**This value is a unique identifier for the user, so it is better to be as random as possible**
5. ### **Strongly Recommended to Use User Authentication**:
Tenant authentication has many limitations, such as document access permissions, Feishu openapi compatibility (does not support searching wiki documents), document creation and editing records, etc., which are not as good as user authentication.
6. ### **Task and User Information Function**:
Want to use AI to help you manage Feishu tasks (list pending tasks, create tasks, assign responsible persons) or find colleague information? Need two steps: ① Use **user authentication** (tenant mode does not provide these capabilities); ② Set `FEISHU_ENABLED_MODULES=document,task` in the configuration. After enabling task, the user query function will be automatically available, without additional configuration.
7. ### **Using Lark International Edition**:
Feishu domestic version does not require additional configuration. If your team uses **Lark International Edition or self-built Feishu service**, you need to set:
```env
FEISHU_BASE_URL=https://open.larksuite.com/open-apis
FEISHU_AUTH_BASE_URL=https://accounts.larksuite.com
```
8. ### **Internal Network Access, External Network Callback Separation**:
If MCP client accesses the service through an internal network address (e.g., `http://feishu-mcp:3333/mcp`), but Feishu OAuth callback must use a public domain name, you can set:
```env
FEISHU_PUBLIC_BASE_URL=https://somo-feishu-mcp.yfgao.net
```
In this way, the client can still connect to the internal network address, while the authorization link returned to the user will use `https://somo-feishu-mcp.yfgao.net/callback` as the callback address.
9. ### **Dynamic Switching of userKey under Multi-Tenant Relay Architecture**:
In a multi-tenant relay architecture, the system integrates and manages tools to uniformly proxy Feishu MCP services. Since the underlying MCP service instances reuse the session layer, different users' requests actually run in a shared session context. Therefore, the system needs to support dynamic switching based on the request header transparent transmission `user-key` to achieve tenant identity isolation and context injection, thereby meeting the needs of multi-users accessing concurrently.
**How to switch userKey**:
- In HTTP Streamable mode, subsequent requests can dynamically update the user identifier of the current session by passing the `user-key` request header
- Passing method: Add `user-key: <new user identifier>` to the request header
- Example scenario: After user A completes the operation, user B's request carries `user-key: userB`, and the system will automatically switch the session to user B's context
> **Note**: This function is only valid in HTTP Streamable mode, SSE and stdio modes do not support dynamic switching.
---
## 🚨 Troubleshooting
### Permission Problem Troubleshooting
First, check the configuration problem: [Step-by-Step Tutorial FEISHU_CONFIG.md](FEISHU_CONFIG.md).
#### Problem 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 has been authorized to the application or the group where the application is located
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: [Self-built application to obtain 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 if there is permission to access the document: [Get document basic information](https://open.feishu.cn/api-explorer?apiName=get&project=docx&resource=document&version=v1)
### Frequently Asked Questions
- **Cannot find the application**: Check if the application has been released and the available range configuration is correct
- **Insufficient permissions**: Refer to [Cloud Document FAQ](https://open.feishu.cn/document/ukTMukTMukTM/uczNzUjL3czM14yN3MTN)
- **Knowledge base access issues**: Refer to [Knowledge Base FAQ](https://open.feishu.cn/document/server-docs/docs/wiki-v2/wiki-qa)
---
## 📚 Developer Wiki
Detailed development documents and technical guides provide comprehensive guidance for learners and contributors:
- **[Wiki Home](https://github.com/cso1z/Feishu-MCP/wiki)** - Complete document index and quick navigation
- **[Architecture Design](https://github.com/cso1z/Feishu-MCP/wiki/Architecture-Design)** - Overall architecture and technical stack description
- **[Core Module Details](https://github.com/cso1z/Feishu-MCP/wiki/Core-Module-Details)** - Implementation details and code examples of each module
- **[Authentication and Authorization](https://github.com/cso1z/Feishu-MCP/wiki/Authentication-and-Authorization-Mechanism)** - Token management and multi-user support mechanism
- **[Developer Guide](https://github.com/cso1z/Feishu-MCP/wiki/Developer-Guide)** - Environment setup, development process, debugging techniques
- **[API Reference](https://github.com/cso1z/Feishu-MCP/wiki/API-Reference-Document)** - Detailed documentation of all tool functions
- **[Best Practices](https://github.com/cso1z/Feishu-MCP/wiki/Best-Practices)** - Code specifications, performance optimization, security practices
- **[MCP Protocol Implementation](https://github.com/cso1z/Feishu-MCP/wiki/MCP-Protocol-Implementation)** - MCP protocol details and transmission layer implementation
---
## 💖 Support the Project
If this project has helped you, consider:
- ⭐ Give the project a Star
- 🐛 Report Bugs and issues
- 💡 Propose new feature suggestions
- 📖 Improve documentation
- 🔀 Submit Pull Request
Your support is our driving force!
## Star History
[](https://www.star-history.com/#cso1z/feishu-mcp&Timeline)
