Feishu MCP Server for API Integration

Overview

The Feishu MCP Server is a service based on the Model Context Protocol that provides seamless integration with Feishu APIs. It enables AI models to interact effortlessly with Feishu services, offering features like document management, bot messaging, chat operations, and multi-dimensional table handling.

Key Features

• Document Services: Read Feishu document content and metadata.
• Bot Services: Send text messages and interactive cards to Feishu chats.
• Chat Services: Manage group chats and chat sessions.
• Multi-Mode Support:
• STDIO Mode: Communicate via standard input/output, ideal for CLI environments.
• HTTP Mode: Provides REST API and SSE connections for web services and distributed deployments.
• Error Handling: Unified error handling with detailed error messages.
• Type Safety: Built with TypeScript for full type definitions.
• Modular Architecture: Easily extendable for new features and additional Feishu API integrations.

Project Structure

Code Structure

/src
  /client        # API client implementations
    /documents   # Document-related API clients
    /bots        # Bot API clients
    /chats       # Chat-related API clients
  /services      # Service layer (business logic and error handling)
    /documents   # Document-related services
    /bots        # Bot-related services
    /chats       # Chat-related services
  /server        # MCP server implementation
    /tools       # MCP tool registration and implementation
  /typings       # Type definitions
  /utils         # Utility functions
  /http          # HTTP server implementation
  /logger        # Logging service
  /consts        # Constant definitions
  config.ts      # Configuration management
  index.ts       # Entry point

Design Principles

• Layered Architecture: Separates concerns into client, service, and tool layers.
• Dependency Direction: Service layer depends on the client layer; tool layer depends on the service layer.
• Error Handling Strategy: Uses FeiShuApiError for unified API error handling.

Quick Start

Prerequisites

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

Installation

1. Clone the repository:

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

1. Install dependencies:

shell pnpm install

1. Create .env file:

env FEISHU_APP_ID=your_app_id FEISHU_APP_SECRET=your_app_secret PORT=3344 LOG_LEVEL=info

Running the Server

Development Mode

pnpm dev

Production Mode

pnpm build
node dist/index.js

STDIO Mode

NODE_ENV=cli node dist/index.js

Configuration

API Documentation

Document Operations

get_feishu_doc_raw

Fetch raw content of a Feishu document.

Parameters:
- docId: Document ID (found in the URL).

Returns: Document text content.

get_feishu_doc_info

Fetch metadata of a Feishu document.

Parameters:
- docId: Document ID.

Returns: Document metadata in JSON format.

Bot Operations

send_feishu_text_message

Send a text message to a Feishu chat.

Parameters:
- chatId: Chat ID.
- text: Text content to send.

Returns: Sending status and message ID.

send_feishu_card

Send an interactive card to a Feishu chat.

Parameters:
- chatId: Chat ID.
- cardContent: Card content in JSON string.

Returns: Sending status and message ID.

Chat Operations

get_feishu_chat_info

Fetch basic information of a Feishu chat.

Parameters:
- chatId: Chat ID.

Returns: Chat information in JSON format.

Multi-Dimensional Table Operations

get_feishu_sheet_meta

Fetch metadata of a Feishu multi-dimensional table.

Parameters:
- appToken: Table ID (found in the URL).

Returns: Table metadata in JSON format.

Development Guide

Code Standards

• Use TypeScript interfaces and type definitions.
• Avoid any type.
• Use Record<string, unknown> instead of object.
• All code, comments, and error messages must be in English.

Error Handling

Use FeiShuApiError for all Feishu API-related errors:

try {
  // API operation
} catch (error) {
  if (error instanceof FeiShuApiError) {
    logger.error(`FeiShu API Error (${error.code}): ${error.message}`);
  } else {
    logger.error('Unexpected error:', error);
  }
  throw new FeiShuApiError('Operation failed', { cause: error });
}

Contribution Guidelines

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'feat: add some amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a Pull Request.

License

MIT