feishu-miqroera-mcp

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

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.

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.github/workflows		.github/workflows
docs		docs
scripts		scripts
src/feishu_mcp		src/feishu_mcp
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

feishu-miqroera-mcp

Table of Contents

Features

Quick Start

1. Clone and install

2. Configure Feishu app credentials

3. Verify the installation

Connect an AI Agent

NanoBot (recommended)

Claude Desktop

Cursor

Cline / Continue / Other MCP-compatible tools

Long-Connection Event Listener

Docker Deployment

Using Docker directly

Using Docker Compose

Full Tool List

Feishu App Permissions

Development & Contributing

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

feishu-miqroera-mcp

Table of Contents

Features

Quick Start

1. Clone and install

2. Configure Feishu app credentials

3. Verify the installation

Connect an AI Agent

NanoBot (recommended)

Claude Desktop

Cursor

Cline / Continue / Other MCP-compatible tools

Long-Connection Event Listener

Docker Deployment

Using Docker directly

Using Docker Compose

Full Tool List

Feishu App Permissions

Development & Contributing

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages