# Feishu Interaction

> Feishu/Lark platform interaction via MCP - documents, tasks, calendar, Bitable, messaging

- Skill: `markus-global/feishu-interaction` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add markus-global/feishu-interaction`
- Raw SKILL.md: https://api.skillmd.com/api/skills/markus-global/feishu-interaction/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: markus-global (https://skillmd.com/u/markus-global)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/markus-global/feishu-interaction

---


# Feishu/Lark Platform Interaction

You have access to the Feishu/Lark platform via MCP tools (prefixed `feishu-lark__`).
This enables you to interact with the user's Feishu workspace: search and read documents,
manage tasks, create calendar events, operate Bitable databases, and send messages.

## Available Capabilities

### Documents (文档)
- `docx.v1.document.rawContent` — Read document content
- `docx.builtin.import` — Import documents (create new docs from content)
- `docx.builtin.search` — Search documents by keyword
- `wiki.v2.space.getNode` — Get Wiki node content
- `wiki.v1.node.search` — Search Wiki nodes

### Tasks (任务)
- `task.v2.task.create` — Create a new task with title, description, due date
- `task.v2.task.patch` — Update an existing task
- `task.v2.task.addMembers` — Add members to a task
- `task.v2.task.addReminders` — Add reminders to a task

### Calendar (日历)
- `calendar.v4.calendarEvent.create` — Create a calendar event
- `calendar.v4.calendarEvent.patch` — Modify a calendar event
- `calendar.v4.calendarEvent.get` — Get calendar event details
- `calendar.v4.freebusy.list` — Query free/busy status
- `calendar.v4.calendar.primary` — Get primary calendar info

### Bitable (多维表格)
- `bitable.v1.appTable.list` — List tables in a base
- `bitable.v1.appTableField.list` — List fields in a table
- `bitable.v1.appTableRecord.search` — Search records
- `bitable.v1.appTableRecord.create` — Create records
- `bitable.v1.appTableRecord.update` — Update records

### Messaging (消息)
- `im.v1.message.create` — Send a message to a chat or user
- `im.v1.message.list` — List messages in a chat
- `im.v1.chat.create` — Create a new group chat
- `im.v1.chat.list` — List chats the bot is in

### Contacts (通讯录)
- `contact.v3.user.batchGetId` — Batch get user IDs by email/mobile

## Best Practices

### Document Operations
1. **Search before read** — Always search for documents first to find the correct `document_id`
2. **Prefer Wiki nodes** — If the user mentions "知识库" or "Wiki", use wiki APIs
3. **Cite sources** — When referencing document content in replies, include the document title

### Task Management
1. **Match user intent** — When user says "帮我创建一个任务", use `task.v2.task.create`
2. **Set due dates** — Always ask for or infer a due date when creating tasks
3. **Add members** — If the user mentions specific people, resolve their user IDs via contacts API first

### Calendar Events
1. **Check availability** — Before creating an event, use `freebusy.list` to check conflicts
2. **Time zones** — Default to Asia/Shanghai unless the user specifies otherwise
3. **Include details** — Set description, location, and attendees when provided

### Bitable Operations
1. **Discover structure** — List tables and fields before searching records
2. **Filter queries** — Use search with filter conditions rather than fetching all records
3. **Batch operations** — For multiple records, prefer batch create/update when available

### Messaging
1. **Format appropriately** — Use markdown formatting for rich messages
2. **Respect context** — Only send messages when the user explicitly asks to notify someone
3. **Interactive cards** — For structured information, use `msg_type: 'interactive'` with card JSON
4. **Send text** — Prefer native tool `feishu_send_message` (or MCP `im.v1.message.create`)
5. **Send local images** — Use native tool `feishu_send_image` with the absolute file path.
   Feishu MCP **cannot** upload images/files. Never claim an image was sent via MCP alone.
6. **Empty chat list** — `im.v1.chat.list` only returns groups the bot has joined. If it returns
   `items: []`, do **not** give up: resolve the user's `open_id` (e.g. via
   `calendar.v4.calendar.primary` → `user_id`, or `contact.v3.user.batchGetId`) and send with
   `receive_id_type=open_id` (p2p / "发到我的飞书").

## Important Notes

- Tool names are prefixed with `feishu-lark__` (e.g., `feishu-lark__docx.builtin.search`)
- Document editing is NOT supported — you can only read and import
- File/image upload via MCP is NOT supported — use `feishu_send_image` for local images
- Always handle API errors gracefully and report them to the user
- Respect rate limits: 1000 requests/minute per API endpoint

## Permission Error Handling

When a tool call returns an error containing `code: 99991672` or "Access denied...scopes required",
it means the Feishu application has not been granted the necessary API permissions. In this case:

1. **Extract the authorization URL** from the error message (starts with `https://open.feishu.cn/app/`)
2. **Present the link to the user** clearly, explaining they need to click it to authorize the required permissions
3. **Do NOT retry** the same tool call — it will continue to fail until permissions are granted
4. **List the missing scopes** mentioned in the error so the user knows what to authorize

Example response format:
> The Feishu app needs additional permissions to perform this operation.
> Please open the following link to authorize, then try again:
>
> [https://open.feishu.cn/app/cli_xxx/auth?q=docs:doc,drive:drive,...](https://open.feishu.cn/app/cli_xxx/auth?q=docs:doc,drive:drive,...)
>
> Missing scopes: docs:doc, drive:drive

Always use the full URL as both the link text AND the href (i.e. `[full_url](full_url)`), so the user can both see the complete URL and click it directly.