Content
# Feishu MCP Server
Provides access to Feishu documents for [Cursor](https://cursor.sh/), [Windsurf](https://codeium.com/windsurf), [Cline](https://cline.bot/), and other AI-driven coding tools, based on the implementation of the [Model Context Protocol](https://modelcontextprotocol.io/introduction) server.
When Cursor can access Feishu document data, it can understand and process document content more accurately and efficiently than other methods (such as copy-pasting text).
## Core Features
### Document Management
- **Create Feishu Document**: Supports creating new Feishu documents in a specified folder.
### Document Content Operations
- **Get Document Information**:
- Retrieve basic document information (title, version, etc.)
- Get the block structure and hierarchy of the document
- Retrieve detailed content of specific blocks
- **Get Document Plain Text Content**: Supports extracting the complete plain text content of the document for analysis and processing.
- **Edit Document Content**:
- **Text Block Operations**:
- Create and update text blocks with rich styles (bold, italic, underline, strikethrough, inline code)
- Supports text color settings (gray, brown, orange, yellow, green, blue, purple)
- Supports text alignment adjustments (left, center, right)
- **Heading Block Operations**: Create different levels of headings from level one to level nine.
- **Code Block Operations**:
- Create code blocks in various programming languages
- Supports code syntax highlighting
- Supports automatic line wrapping settings
- **List Operations**:
- Create ordered lists (numbered lists)
- Create unordered lists (bulleted lists)
- **Batch Content Creation**: Supports creating multiple different types of content blocks in a single operation.
### Planned Features
- **Advanced Content Insertion**:
- Table Insertion: Supports structured data in rows and columns
- Insert Charts: Supports various types of data visualization charts
- Insert Flowcharts: Supports flowcharts and mind maps
- Insert Formulas: Supports mathematical formulas and scientific symbols
- Content recognition and parsing for charts and flowcharts.
For a quick start, see the [Configuration](#配置) section:
```bash
npx feishu-mcp --feishu-app-id=<your Feishu app ID> --feishu-app-secret=<your Feishu app secret>
```
## How It Works
1. Open the editor in Cursor's Agent mode.
2. Paste the link to the Feishu document.
3. Request Cursor to perform operations based on the Feishu document—such as analyzing document content or creating related code.
4. Cursor will fetch relevant metadata from Feishu and use it to assist in code writing.
This MCP server is specifically designed for Cursor. Before responding to content from the [Feishu API](https://open.feishu.cn/document/home/introduction-to-lark-open-platform/overview), it simplifies and transforms the response to ensure that only the most relevant document information is provided to the model.
## Installation
### Quickly Run the Server Using NPM
You can quickly run the server using NPM without installing or building the repository:
```bash
npx feishu-mcp --feishu-app-id=<your Feishu app ID> --feishu-app-secret=<your Feishu app secret>
# Or
pnpx feishu-mcp --feishu-app-id=<your Feishu app ID> --feishu-app-secret=<your Feishu app secret>
# Or
yarn dlx feishu-mcp --feishu-app-id=<your Feishu app ID> --feishu-app-secret=<your Feishu app secret>
# Or
bunx feishu-mcp --feishu-app-id=<your Feishu app ID> --feishu-app-secret=<your Feishu app secret>
```
**Published on the Smithery platform, accessible at: https://smithery.ai/server/@cso1z/feishu-mcp**
Instructions on how to create a Feishu app and obtain app credentials can be found [here](https://open.feishu.cn/document/home/develop-a-bot-in-5-minutes/create-an-app).
### JSON Configuration for Tools Using Configuration Files
Many tools like Windsurf, Cline, and [Claude Desktop](https://claude.ai/download) use configuration files to start the server.
The `feishu-mcp` server can be configured by adding the following content to the configuration file:
```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>"
}
}
}
}
```
### Run the Server from Local Source Code
1. Clone the repository.
2. Use `pnpm install` to install dependencies.
3. Copy `.env.example` to `.env` and fill in your [Feishu app credentials](https://open.feishu.cn/document/home/develop-a-bot-in-5-minutes/create-an-app).
4. Use `pnpm run dev` to run the server, and you can use any flags from the [Command Line Arguments](#命令行参数) section.
## Configuration
The server can be configured using environment variables (via the `.env` file) or command line arguments. Command line arguments take precedence over environment variables.
### Environment Variables
- `FEISHU_APP_ID`: Your [Feishu App ID](https://open.feishu.cn/document/home/develop-a-bot-in-5-minutes/create-an-app) (required)
- `FEISHU_APP_SECRET`: Your [Feishu App Secret](https://open.feishu.cn/document/home/develop-a-bot-in-5-minutes/create-an-app) (required)
- `PORT`: The port to run the server (default: 3333)
### Command Line Arguments
- `--version`: Show version number
- `--feishu-app-id`: Your Feishu App ID
- `--feishu-app-secret`: Your Feishu App Secret
- `--port`: The port to run the server
- `--stdio`: Run the server in command mode instead of the default HTTP/SSE
- `--help`: Show help menu
## Connect to Cursor
### Configure Cursor
1. Open Cursor settings.
2. Navigate to `Settings > AI > MCP Servers`.
3. Add a new server with the URL `http://localhost:3333` (or the port you configured).
4. Click "Verify Connection" to ensure the connection is successful.
## Usage
1. In Cursor, open the AI panel (default shortcut `Cmd+K` or `Ctrl+K`).
2. If you need to create a new Feishu document to edit information, you should specify a folderToken, which can open a Feishu document directory like: `https://vq5xxxxx7bc.feishu.cn/drive/folder/FPKvfjdxxxxx706RnOc`.
3. If you need to modify the content of a Feishu document, you should clearly provide the link to the Feishu document, for example: `https://vq5ixxxx7bc.feishu.cn/docx/J6T0d6exxxxxxxDdc1zqwnph`.
4. Ask questions about the document or request operations based on the document content.
5. Creating and editing documents requires permissions; you can test your account on the Feishu Open Platform at `https://open.feishu.cn/api-explorer/cli_a75a8ca0ac79100c?apiName=tenant_access_token_internal&from=op_doc&project=auth&resource=auth&version=v3`.
## Document Permissions and Troubleshooting
### Permission Types
Permissions are divided into two types: bot permissions and document access permissions.
### Permission Verification and Troubleshooting
1. Obtain token: [https://open.feishu.cn/api-explorer/cli_a7582508c93ad00d?apiName=tenant_access_token_internal&project=auth&resource=auth&version=v3](https://open.feishu.cn/api-explorer/cli_a7582508c93ad00d?apiName=tenant_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: [https://open.feishu.cn/api-explorer/cli_a7582508c93ad00d?apiName=get&project=docx&resource=document&version=v1](https://open.feishu.cn/api-explorer/cli_a7582508c93ad00d?apiName=get&project=docx&resource=document&version=v1).
### Troubleshooting Methods
Test permissions on the Feishu Developer Platform (debugging on the open platform will provide ample prompt information and guidance when failures occur).
### Document Authorization
If you encounter permission issues, please refer to the [Common Issues with Cloud Documents](https://open.feishu.cn/document/ukTMukTMukTM/uczNzUjL3czM14yN3MTN), paying special attention to how to grant document permissions to applications or users.
## Cursor Best Practices
Add Rules to guide the model's operational process.
`When uploading documents to Feishu, please follow these operational guidelines: 1. If no specific folderToken is specified, the default is FPKvf*********6RnOc. 2. In case of block creation failure, query all block information in the document to confirm whether a failure has indeed occurred. 3. If you need to append information to an existing document, first retrieve all block information of that document and determine the content to insert and its index position based on the returned results. 4. Once all document content modifications are complete, please provide the document link in the following format: https://vq5iay***bc.feishu.cn/docx/documentId. 5. When retrieving document information, prioritize querying its plain text content; if that does not suffice, query all blocks to determine the content.`
## License
MIT
