README.en.md•9.76 kB
[](https://lobehub.com/mcp/ztxtxwd-open-feishu-mcp-server)
# Feishu MCP Server
[中文文档](README.md)
This is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server that supports remote connections with built-in Feishu OAuth authentication.
This project is modified from [cloudflare/ai/demos/remote-mcp-github-oauth](https://github.com/cloudflare/ai/tree/main/demos/remote-mcp-github-oauth), replacing GitHub OAuth with Feishu OAuth.
You can deploy it to your own Cloudflare account, and after creating your own Feishu OAuth client application, you'll have a fully functional remote MCP server. Users can connect to your MCP server by logging in with their Feishu account.
## 📋 Table of Contents
- [Comparison with Official Feishu MCP Server](#-comparison-with-official-feishu-mcp-server)
- [Features](#-features)
- [Quick Start](#-quick-start)
- [Deployment Methods](#-deployment-methods)
- [Production Deployment](#production-deployment)
- [Local Development Environment](#local-development-environment)
- [Client Integration](#-client-integration)
- [Testing with Inspector](#testing-with-inspector)
- [Using Cursor](#using-cursor)
- [Using ChatWise](#using-chatwise)
- [Access Control](#-access-control)
- [Tool Development Roadmap](#-tool-development-roadmap)
- [Technical Architecture](#-technical-architecture)
- [Development Guide](#-development-guide)
## 🆚 Comparison with Official Feishu MCP Server
While Feishu officially released an MCP Server, this project has significant advantages in the following areas:
### 🎯 Zero-Configuration Experience
- **This Project**: Users need no manual configuration, uses `user_access_token` throughout with automatic refresh on expiration
- **Official Project**: Requires users to manually configure multiple parameters with complex setup
### 🚀 Ultimate Usability Optimization
- **This Project**: Deep optimization of tool size and structure, especially for complex features like document block creation and nested block creation tools, ensuring proper functionality in Cursor and other clients
- **Official Project**: Simple API-to-MCP tool conversion, with some tools being too large and having usability issues in practice
### 🌐 Cutting-Edge Infrastructure
- Supports deployment on Cloudflare Workers, enjoying the industry's most advanced edge computing infrastructure
## ✨ Features
- 🎯 **Zero-Configuration Experience**: No manual parameter configuration needed, automatic `user_access_token` management and refresh
- 🔐 **Feishu OAuth Authentication**: Secure user identity verification
- 🌐 **Remote MCP Server**: Supports multi-client connections
- 🚀 **Cloudflare Workers**: High-performance, globally distributed deployment with cutting-edge edge computing infrastructure
- 🛠️ **Deeply Optimized Toolset**: Specially optimized for document creation, nested blocks, and other complex tools ensuring proper functionality across various clients
- 🔧 **Local Development Support**: Convenient development and testing environment
- ⚡ **Ultimate Usability**: Significant improvement in practical usage experience and stability compared to the official MCP Server
## 🚀 Quick Start
### Prerequisites
- Node.js 18+ and npm
- Cloudflare account
- Feishu Open Platform account
### Installation
```bash
# Clone repository
git clone <repository-url>
cd open-feishu-mcp-server
# Install dependencies
npm install
```
## 🚀 Deployment Methods
### Production Deployment
#### Step 1: Create Feishu Application
1. Visit [Feishu Open Platform](https://open.feishu.cn/) and log in
2. Click "Developer Console" and create a new application
3. Configure permissions in application settings:
- Go to "Permissions & Features" and add the following permissions:
- "Get User ID" (auth:user.id:read)
- "Get User Task Information" (task:task:read)
- "Get User Authorization Credentials" (offline_access)
- "Get User Basic Information" (user_profile)
...
4. Note your **App ID** and **App Secret**
#### Step 2: Configure Cloudflare Environment
```bash
# Set necessary secrets
wrangler secret put FEISHU_APP_ID
wrangler secret put FEISHU_APP_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY # Generate with: openssl rand -hex 32
# Create KV namespace
wrangler kv:namespace create "OAUTH_KV"
```
#### Step 3: Update Configuration File
Update the KV namespace configuration in `wrangler.toml` with the KV ID obtained from Step 2.
#### Step 4: Deploy Server
```bash
npm run deploy
```
After deployment, note your actual subdomain (displayed in deployment logs).
#### Step 5: Configure Redirect URL
Return to Feishu application settings:
1. Go to "Security Settings"
2. Add redirect URL: `https://feishu-mcp-server.<your-actual-subdomain>.workers.dev/callback`
### Local Development Environment
#### Configure Local Environment
1. **Configure Feishu Application**:
- Add to "Security Settings" in Feishu app: `http://localhost:8788/callback`
- Ensure required permissions (same as production environment)
2. **Create Environment Variables File**:
Create `.dev.vars` file in project root:
```
FEISHU_APP_ID=your_development_feishu_app_id
FEISHU_APP_SECRET=your_development_feishu_app_secret
COOKIE_ENCRYPTION_KEY=any_random_string_here
```
#### Start Local Server
```bash
npm run dev
```
Server will run at `http://localhost:8788`.
## 🔌 Client Integration
### Testing with Inspector
Test your server using the official MCP Inspector:
```bash
npx @modelcontextprotocol/inspector@latest
```
**Connection URLs**:
- Production: `https://feishu-mcp-server.<your-subdomain>.workers.dev/sse`
- Local: `http://localhost:8788/sse`
### Using Cursor
Quick setup with one-click install button:
[](https://cursor.com/install-mcp?name=feishu&config=eyJ1cmwiOiJodHRwOi8vbG9jYWxob3N0Ojg3ODgvc3NlIn0%3D)
Or manual configuration:
```json
{
"mcpServers": {
"feishu": {
"url": "http://localhost:8788/sse"
}
}
}
```
### Using ChatWise
1. **Configuration Steps**:
- Open ChatWise settings interface
- Navigate to tools options
- Add new command line input/output (stdio)
- Command: `npx -y mcp-remote ${URL}`
2. **Connection URLs**:
- Local: `http://localhost:8788/sse`
- Production: `https://feishu-mcp-server.<your-subdomain>.workers.dev/sse`
3. **First Use**:
- After saving configuration, Feishu OAuth login page will automatically open
- Complete authorization to use Feishu-related features
## 🔐 Access Control
- **Authentication**: Uses Feishu OAuth for user identity verification
- **Permission Scope**: All authenticated Feishu users can access all tools
## 📋 Tool Development Roadmap
### 🚧 Currently in Development (Feishu Documents)
- **🔧 Development Assistant Tools**
- ✅ Developer document content search and recall
- **📄 Document Basic Operations**
- ✅ Document block tree structure retrieval
- ✅ Get block type creation parameter schema
- ✅ Create document blocks (supports various block types)
- ✅ Update document block content
- ✅ Batch delete document blocks
- **🔧 Document Advanced Features**
- ✅ Table creation and operations
- ✅ Image, video, file upload and insertion
- ✅ Markdown import functionality
- ✅ Media upload and management
- ✅ Document search
### 🎯 Future Plans
- **📊 Spreadsheets (Sheets)**
- 📋 Worksheet basic operations (create, delete, rename)
- 📋 Cell data read/write
- 📋 Formula calculation and application
- 📋 Chart creation and editing
- 📋 Data filtering and sorting
- 📋 Collaboration and permission management
- **🗃️ Multi-dimensional Tables (Base/Bitable)**
- 📋 Data table basic operations
- 📋 Record CRUD operations
- 📋 Field type management
- 📋 View creation and configuration
- 📋 Automation rule setup
- 📋 Data import/export
...
**Legend**: ✅ Completed | 🔄 In Development | 📋 Planned
## 🛠️ Technical Architecture
### Architecture Components
#### OAuth Provider
Complete OAuth 2.1 server implementation that handles:
- MCP client authentication
- Feishu OAuth service connection management
- Secure token management in KV storage
#### Durable MCP
MCP extension based on Cloudflare Durable Objects:
- Persistent state management
- Authentication context storage
- User information access via `this.props`
- Conditional tool availability based on user identity
#### MCP Remote
Supports remote MCP client connections:
- Defines client-server communication protocol
- Provides structured tool definition approach
- Handles request/response serialization
- Maintains SSE connections
## 👨💻 Development Guide
### MCP Server (Powered by [Cloudflare Workers](https://developers.cloudflare.com/workers/))
This project implements dual OAuth roles:
* Acts as OAuth **Server** to MCP clients
* Acts as OAuth **Client** to Feishu OAuth service
### Tool Development
Current tools use user access tokens for authentication, ensuring:
- Secure Feishu API access
- User permission-based feature access
- Complete error handling and logging
---
**📝 Note**: Ensure all environment variables and Feishu application settings are properly configured before deployment. If you encounter issues, please check Feishu application permission configuration and redirect URL settings.
## Star History
[](https://star-history.com/#ztxtxwd/open-feishu-mcp-server&Date)