FeiShu MCP server

The Feishu MCP Server is a service based on the Model Context Protocol that provides Feishu API integration, allowing AI models to easily interact with Feishu services. It offers capabilities for document access, chat management, and bot operations through both STDIO and HTTP interfaces.

Prerequisites

• Node.js 23.0 or higher
• pnpm package manager
• Valid Feishu developer account and created application

Installation

1. Clone the repository

git clone https://github.com/yourusername/feishu-mcp-server.git
cd feishu-mcp-server

2. Install dependencies

pnpm install

3. Create a .env file

# Feishu app credentials (required)
FEISHU_APP_ID=your_app_id
FEISHU_APP_SECRET=your_app_secret

# Server configuration (optional)
PORT=3344
LOG_LEVEL=info

Running the Server

Development Mode

# Development mode (auto-restart)
pnpm dev

# Or regular start
pnpm start

Production Mode

# Build the project
pnpm build

# Run the compiled code
node dist/index.js

STDIO Mode

# Method 1: Using environment variables
NODE_ENV=cli node dist/index.js

# Method 2: Using command line parameters
node dist/index.js --stdio

Configuration Options

Available API Tools

Document Operations

get_feishu_doc_raw

Gets the raw content of a Feishu document.

Parameters:

• docId - Document ID, typically found in the URL (e.g., feishu.cn/docx/<documentId>)

Returns:

• The document's text content

get_feishu_doc_info

Gets metadata information about a Feishu document.

Parameters:

• docId - Document ID

Returns:

• Document metadata in JSON format

Bot Operations

send_feishu_text_message

Sends a text message to a Feishu chat.

Parameters:

• chatId - Chat ID
• text - Text content to send

Returns:

• Send status and message ID

send_feishu_card

Sends an interactive card to a Feishu chat.

Parameters:

• chatId - Chat ID
• cardContent - Card content (JSON string)

Returns:

• Send status and message ID

Chat Operations

get_feishu_chat_info

Gets basic information about a Feishu chat.

Parameters:

• chatId - Chat ID

Returns:

• Basic chat information in JSON format

Bitable Operations

get_feishu_sheet_meta

Gets metadata about a Feishu Bitable.

Parameters:

• appToken - Bitable ID, typically found in the URL (e.g., feishu.cn/base/<appToken> or feishu.cn/app/<appToken>)

Returns:

• Bitable metadata in JSON format

get_feishu_sheet_tables

Gets the list of tables in a Feishu Bitable.

Parameters:

• appToken - Bitable ID
• pageSize - Number of tables to return per page (optional, default 20, max 100)
• pageToken - Pagination token (optional, for getting the next page)

Returns:

• List of tables in JSON format

get_feishu_sheet_views

Gets the list of views in a Feishu Bitable table.

Parameters:

• appToken - Bitable ID
• tableId - Table ID
• pageSize - Number of views to return per page (optional, default 20, max 100)
• pageToken - Pagination token (optional)

Returns:

• List of views in JSON format

get_feishu_sheet_view

Gets detailed information about a specific view in a Feishu Bitable table.

Parameters:

• appToken - Bitable ID
• tableId - Table ID
• viewId - View ID

Returns:

• View details in JSON format

get_feishu_sheet_records

Gets records from a Feishu Bitable table.

Parameters:

• appToken - Bitable ID
• tableId - Table ID
• viewId - View ID (optional, uses default view if not specified)
• fieldIds - List of field IDs to return (optional)
• filter - Filter condition in FQL format (optional)
• sort - Sort condition in JSON format (optional)
• pageSize - Number of records to return per page (optional, default 20, max 100)
• pageToken - Pagination token (optional)

Returns:

• List of records in JSON format

get_feishu_sheet_record

Gets a single record from a Feishu Bitable table.

Parameters:

• appToken - Bitable ID
• tableId - Table ID
• recordId - Record ID
• fieldIds - List of field IDs to return (optional)

Returns:

• Single record in JSON format

Troubleshooting

Authentication Failures

Problem: API requests return authentication errors

Solution:

• Check if the App ID and Secret are correct
• Verify that the application has the required permission scopes
• Ensure the server time is properly synchronized

Token Refresh Issues

Problem: Token refresh fails

Solution:

• Set a shorter token cache duration
• Check network connection stability
• Verify the application status in the Feishu developer platform

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.