feishu-mcp-server

feishu-mcp-server

35
communicationai_chatbotdeveloper_tools

Feishu MCP Server is a Model Context Protocol-based service for integrating AI models with Feishu, offering capabilities like document, bot, and chat management. It supports multiple modes, robust error handling, and a modular architecture allowing for feature extensions.

Feishu MCP Server

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.

Features

  • Document Service: Read Feishu document content and metadata
  • Bot Service: Send text messages and interactive cards to Feishu chats
  • Chat Service: Manage groups and chat sessions
  • Multiple Modes Support:
    • STDIO Mode: Communication through standard input/output, suitable for CLI environments and integration into other applications
    • HTTP Mode: Provides REST API and SSE connection, suitable for web services and distributed deployment
  • Comprehensive Error Handling: Unified error handling mechanism with detailed error information
  • Type Safety: Fully typed using TypeScript
  • Modular Architecture: Easy to extend new features and integrate other Feishu APIs

Project Architecture

Design Principles

  1. Layered Responsibilities:

    • Client Layer: Handles HTTP request details, does not include business logic
    • Service Layer: Implements business logic
    • Tools Layer: Handles parameter validation and returns formatted results

  2. Dependency Direction:

    • Service layer depends on the client layer
    • Tools layer depends on the service layer

  3. Error Handling Strategy:

    • Uses FeiShuApiError for API errors
    • Client layer returns raw errors, service layer catches and converts errors

Workflow

  1. MCP server receives request (STDIO or HTTP)
  2. Tools layer validates parameters, calls the corresponding service
  3. Service layer implements business logic, calls client
  4. Client executes API request, returns result
  5. Result processed by service layer, returned to tools layer
  6. Tools layer formats and returns result to MCP server

Quickstart

Prerequisites

  • Node.js 23.0+
  • pnpm package manager
  • Valid Feishu developer account

Installation

  1. Clone repository
  2. Install dependencies using pnpm install
  3. Set up a .env file with Feishu app credentials

Running Service

  • Development Mode: Use pnpm dev for auto-restart, or pnpm start
  • Production Mode: Build project with pnpm build and run with node dist/index.js
  • STDIO Mode: Use environment variable NODE_ENV=cli or --stdio flag in command line