feishu-miqroera-mcp

🤖 Feishu MCP Server — Let AI Agents directly control Feishu: send messages, create calendars, manage tasks, and write cloud documents.

Python License: MIT MCP

Features

This project implements an MCP (Model Context Protocol) Server that wraps Feishu’s core capabilities as structured AI tools, enabling any MCP-compatible AI Agent / LLM toolchain to:

Capability	Functions
💬 Messages	Send & reply to group messages, @mention members, Markdown format
📅 Calendar	Create/query group calendars, create events, invite attendees
✅ Tasks	Create tasks, assign owners, set due dates
📄 Documents	Create cloud docs, write Markdown content, upload files, one-click share links, set collaborator permissions
👥 Users	Get group member lists, resolve users by name
🔔 Events	Receive Feishu push events via long-connection WebSocket in real time (no public IP required)

Quick Start

1. Clone and install

git clone https://github.com/your-username/feishu-miqroera-mcp.git
cd feishu-miqroera-mcp

python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -e .

2. Configure Feishu app credentials

cp .env.example .env

Edit .env:

FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

How to get credentials: log in to the Feishu Open Platform → create an in-house app → go to the "Credentials & Basic Info" page

3. Verify the installation

# Confirm the MCP server starts correctly (Ctrl+C to exit)
.venv\Scripts\python.exe -m feishu_mcp.server

You should see MCP server running on stdio indicating success.

Connect an AI Agent

NanoBot (recommended)

NanoBot is a lightweight multimodal AI Agent framework with native support for MCP Servers and Feishu channels.

Step 1: Edit the NanoBot config file

# Config file location (auto-created)
~/.nanobot/config.json        # macOS / Linux
%USERPROFILE%\.nanobot\config.json  # Windows

Step 2: Add feishu-mcp to tools.mcpServers

{
  "tools": {
    "mcpServers": {
      "feishu-mcp": {
        "command": "C:/path/to/feishu-miqroera-mcp/.venv/Scripts/python.exe",
        "args": ["-m", "feishu_mcp.server"],
        "env": {
          "FEISHU_APP_ID": "cli_xxxxxxxxxxxxxxxxxx",
          "FEISHU_APP_SECRET": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        }
      }
    }
  },
  "channels": {
    "feishu": {
      "appId": "cli_xxxxxxxxxxxxxxxxxx",
      "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  }
}

Windows note: Use forward slashes / or double backslashes \\ in paths

Step 3: Start NanoBot

nanobot run

NanoBot will automatically establish a Feishu long connection; the AI can then drive Feishu operations via natural language.

Claude Desktop

Step 1: Locate the config file

OS	Path
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`

Step 2: Add the MCP Server config

{
  "mcpServers": {
    "feishu-mcp": {
      "command": "C:/path/to/feishu-miqroera-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "feishu_mcp.server"],
      "env": {
        "FEISHU_APP_ID": "cli_xxxxxxxxxxxxxxxxxx",
        "FEISHU_APP_SECRET": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

macOS example: "command": "/Users/yourname/feishu-miqroera-mcp/.venv/bin/python"

Step 3: Restart Claude Desktop

After restarting, look for the 🔧 icon in the chat input area and confirm "feishu-mcp" is loaded.

Cursor

Step 1: Locate the config file

<project root>/.cursor/mcp.json

Or global config:

OS	Path
Windows	`%USERPROFILE%\.cursor\mcp.json`
macOS	`~/.cursor/mcp.json`

Step 2: Add config

{
  "mcpServers": {
    "feishu-mcp": {
      "command": "C:/path/to/feishu-miqroera-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "feishu_mcp.server"],
      "env": {
        "FEISHU_APP_ID": "cli_xxxxxxxxxxxxxxxxxx",
        "FEISHU_APP_SECRET": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Step 3: Open Cursor → Settings → MCP → Confirm feishu-mcp status is green

Cline / Continue / Other MCP-compatible tools

All tools that support MCP stdio transport can connect using the same config format:

{
  "command": "/absolute/path/to/.venv/bin/python",
  "args": ["-m", "feishu_mcp.server"],
  "env": {
    "FEISHU_APP_ID": "cli_xxx",
    "FEISHU_APP_SECRET": "xxx"
  }
}

Long-Connection Event Listener

Feishu's long connection (WebSocket) requires no public IP and no ngrok — receive Feishu push events directly from behind NAT.

# Start the event listener standalone (runs 24/7)
.venv\Scripts\python.exe -m feishu_mcp.webhook.longconn

Example log output after startup:

INFO  Connecting to Feishu WebSocket: wss://msg-frontier.feishu.cn/ws/v2
INFO  Feishu long connection established
INFO  Received message event: chat_id=oc_xxx, sender=ou_xxx, text=Hello

Receiving events in your own application code:

import lark_oapi as lark

client = lark.Client.builder() \
    .app_id("cli_xxx") \
    .app_secret("xxx") \
    .event_callback(lark.EventType.IM_MESSAGE_RECEIVE_V1, your_handler) \
    .build()

ws = lark.ws.Client(app_id, app_secret, event_handler=client.event_handler)
ws.start()

Docker Deployment

Using Docker directly

# Build image
docker build -t feishu-miqroera-mcp .

# Start Feishu event listener (background)
docker run -d \
  --name feishu-listener \
  --env-file .env \
  --restart unless-stopped \
  feishu-miqroera-mcp \
  feishu_mcp.webhook.longconn

# View logs
docker logs -f feishu-listener

Using Docker Compose

# Copy and fill in env vars
cp .env.example .env
# Edit .env with APP_ID and APP_SECRET

# Start event listener
docker compose up -d feishu-listener

# Check status
docker compose ps

# View logs
docker compose logs -f feishu-listener

MCP Server (stdio) is usually invoked directly as a local process by the AI Agent framework and does not need to be containerized.
Docker is primarily used for persistently running the event listener.

Full Tool List

Tool	Description
`get_chat_members`	Get the member list of a group
`resolve_users_by_name`	Look up users in a group by name
`send_message`	Send a text/rich-text message to a group or user
`reply_message`	Reply to a specific message
`get_or_create_group_calendar`	Get or create a shared group calendar
`create_calendar_event`	Create an event in a calendar
`add_event_attendees`	Add attendees to a calendar event
`list_calendar_events`	Query the list of calendar events
`create_task`	Create a Feishu task (with due time and description)
`assign_task`	Assign an owner to a task
`add_task_to_list`	Add a task to a tasklist
`list_tasks`	Query the task list
`create_folder`	Create a folder in Drive
`create_document`	Create a Feishu cloud document
`write_document_markdown`	Write Markdown content into a document (accepts docx `document_id` or wiki `node_token`)
`upload_file`	Upload a file to Feishu Drive
`upload_file_and_share`	Upload a file and return a shareable link in one step (upload + set permission + get link)
`insert_file_block`	Insert a file attachment block into a document (accepts docx `document_id` or wiki `node_token`)
`set_doc_permission`	Add collaborators to a document (supports users or groups)
`set_doc_public_access`	Set document public access / link sharing permission
`get_share_link`	Get the sharing link for a document
`grant_permission_request`	Handle a permission request and authorize the applicant

See docs/api.md for full parameter details.

Feishu App Permissions

Enable the following permissions in your app's management page on the Feishu Developer Console:

Permission	Purpose
`im:message`	Send/receive messages
`im:message.group_at_msg`	Group @mention feature
`im:chat.members:read`	Read group members
`task:task`	Task read/write
`calendar:calendar`	Calendar read/write
`drive:drive`	Drive/document read/write
`docx:document`	Cloud document content editing
`wiki:wiki:readonly`	Resolve wiki node tokens to docx document IDs (required if documents are wiki-mounted)

Path to enable permissions: App Management → Permission Management → Enable the above permissions → Publish version.

Development & Contributing

# Run unit tests
pytest tests/ -v

# Run integration tests (requires real Feishu credentials)
pytest tests/integration/ -v

# Format code
ruff format src/ tests/

# Lint check
ruff check src/ tests/

See CONTRIBUTING.md for details.

feishu-mcp