feishu-miqroera-mcp

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

---

Table of Contents

• Features
• Quick Start
• Connect an AI Agent
  • NanoBot (recommended)
  • Claude Desktop
  • Cursor
  • Cline / Continue / Other MCP-compatible tools
• Long-Connection Event Listener
• Docker Deployment
• Full Tool List
• Feishu App Permissions
• Development & Contributing

---

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.

---

License

MIT © 2026 feishu-miqroera-mcp contributors