lark-messages

Lark Messages (飞书消息与群组)

以用户身份查看和管理飞书群聊和消息，包括查看群列表、群成员、历史消息等。

Access and manage Lark group chats and messages as the authenticated user, including viewing group lists, members, and message history.

Quick Start

List My Groups (查看我的群聊)

显示我加入的所有群聊
List all my group chats

Get Group Members (查看群成员)

显示"产品团队"群的所有成员
Show members of the "Engineering Team" group

Read Messages (读取消息)

获取"产品团队"群最近的消息
Get recent messages from the "Engineering Team" group

Send Messages (发送消息)

在"产品团队"群发送消息："会议推迟到明天"
Send message to "Engineering Team": "Meeting rescheduled to tomorrow"

Key Features

1. Group Management (群组管理)

List and search groups that the user is a member of:

Available MCP Tools:

• mcp__lark__im_v1_chat_list - Get user's group chats
• mcp__lark__im_v1_chat_create - Create a new group (admin only)

List Parameters:

• page_size: Number of groups per page (max 100)
• page_token: For pagination
• sort_type: Sort by creation time or activity
  • ByCreateTimeAsc: By creation time (ascending)
  • ByActiveTimeDesc: By recent activity (descending)

2. Group Members (群成员)

View and manage group membership:

Available MCP Tools:

• mcp__lark__im_v1_chatMembers_get - Get group member list
• mcp__lark__contact_v3_user_batchGetId - Get user IDs by email/mobile

Member Information:

• Member ID (open_id, union_id, user_id)
• Member name
• Join time
• Member role (owner, admin, member)

3. Message Access (消息访问)

Read message history from groups:

Available MCP Tools:

• mcp__lark__im_v1_message_list - Get chat history
• mcp__lark__im_v1_message_create - Send messages

Message List Parameters:

• container_id: Group chat_id or thread_id
• container_id_type: "chat" or "thread"
• sort_type: Sort by creation time (asc/desc)
• page_size: Messages per page (max 100)
• start_time & end_time: Time range filter (Unix timestamp)

4. Send Messages (发送消息)

Send messages to groups or individuals:

Message Types:

• text: Plain text messages
• post: Rich text messages
• image: Image messages
• file: File attachments
• interactive: Card messages

Common Workflows

Workflow 1: Find and Read Group Messages

1. User: "显示工程团队群的最新消息"
2. Assistant uses: mcp__lark__im_v1_chat_list
   - Get list of user's groups
3. Find group matching "工程团队"
4. Assistant uses: mcp__lark__im_v1_message_list
   - container_id: chat_id
   - container_id_type: "chat"
   - page_size: 20
5. Display recent messages with timestamps and senders

Workflow 2: Get Group Member List

1. User: "谁在产品团队群里?"
2. Assistant uses: mcp__lark__im_v1_chat_list
   - Find group matching "产品团队"
3. Assistant uses: mcp__lark__im_v1_chatMembers_get
   - chat_id: found_chat_id
   - page_size: 100
4. Display member list with names and roles

Workflow 3: Send Message to Group

1. User: "给工程团队发消息：今天的会议取消了"
2. Assistant uses: mcp__lark__im_v1_chat_list
   - Find group matching "工程团队"
3. Assistant uses: mcp__lark__im_v1_message_create
   - receive_id_type: "chat_id"
   - receive_id: found_chat_id
   - msg_type: "text"
   - content: JSON with text
4. Confirm message sent

Examples (示例)

Example 1: List Groups (列出群聊)

User (Chinese):

显示我加入的所有工作群

Assistant Response:

我会列出你加入的所有群聊。

<uses mcp__lark__im_v1_chat_list>
- sort_type: ByActiveTimeDesc
- page_size: 50

你加入了以下 8 个群聊:

1. **产品团队** (12 members)
   - 最后活跃: 5分钟前
   - ID: oc_xxx123

2. **工程部全体** (45 members)
   - 最后活跃: 1小时前
   - ID: oc_xxx124

3. **设计团队** (8 members)
   - 最后活跃: 2小时前
   - ID: oc_xxx125

4. **周报汇总** (25 members)
   - 最后活跃: 1天前
   - ID: oc_xxx126

[... more groups ...]

需要查看哪个群的详细信息?

Example 2: Read Group Messages (读取群消息)

User (English):

Show me the last 10 messages from the "Product Team" group

Assistant Response:

I'll get the recent messages from the Product Team group.

<uses mcp__lark__im_v1_chat_list to find the group>
<uses mcp__lark__im_v1_message_list>
- container_id: oc_xxx123
- container_id_type: "chat"
- page_size: 10
- sort_type: ByCreateTimeDesc

Here are the last 10 messages from **Product Team**:

---

**张三** (5 min ago):
今天的产品评审会推迟到下午3点

**李四** (10 min ago):
好的,收到

**王五** (15 min ago):
@张三 新版本的原型图已经更新了,请查看 [链接]

**张三** (20 min ago):
👍

**李四** (25 min ago):
这周的sprint目标完成了80%,还剩两个任务

[... more messages ...]

Would you like me to get more messages or search for specific content?

Example 3: Get Group Members (获取群成员)

User (Chinese):

产品团队群有哪些成员?

Assistant Response:

我会获取产品团队群的成员列表。

<uses mcp__lark__im_v1_chat_list to find the group>
<uses mcp__lark__im_v1_chatMembers_get>
- chat_id: oc_xxx123
- page_size: 100

**产品团队** 共有 12 位成员:

**管理员:**
1. 张三 (群主) - @zhangsan
2. 李四 (管理员) - @lisi

**成员:**
3. 王五 - @wangwu
4. 赵六 - @zhaoliu
5. 孙七 - @sunqi
6. 周八 - @zhouba
7. 吴九 - @wujiu
8. 郑十 - @zhengshi
9. 钱十一 - @qianshiyi
10. 孙十二 - @sunshier
11. 李十三 - @lishisan
12. 周十四 - @zhoushisi

需要了解某位成员的更多信息吗?

Example 4: Send Message (发送消息)

User (English):

Send a message to the "Engineering Team" group: "Code review session at 3 PM today"

Assistant Response:

I'll send that message to the Engineering Team group.

<uses mcp__lark__im_v1_chat_list to find the group>
<uses mcp__lark__im_v1_message_create>
- receive_id_type: "chat_id"
- receive_id: oc_xxx124
- msg_type: "text"
- content: {"text": "Code review session at 3 PM today"}

✅ Message sent successfully to **Engineering Team** group.

The message "Code review session at 3 PM today" has been delivered to all 45 members.

Example 5: Search Messages by Time Range (按时间范围搜索消息)

User (Chinese):

显示产品团队群昨天的所有消息

Assistant Response:

我会获取产品团队群昨天的消息。

<calculate time range for yesterday>
<uses mcp__lark__im_v1_message_list>
- container_id: oc_xxx123
- container_id_type: "chat"
- start_time: 1705104000 (2024-01-13 00:00:00)
- end_time: 1705190400 (2024-01-14 00:00:00)
- sort_type: ByCreateTimeAsc

找到 **昨天 (2024-01-13)** 的 24 条消息:

**上午:**
- 09:15 张三: 早上好,今天的站会改到10点
- 09:20 李四: 收到
- 10:05 王五: 昨天提的bug已经修复了

**下午:**
- 14:30 赵六: 新功能的设计稿已更新
- 15:45 张三: @all 请大家review一下Q1的路线图
- 16:20 孙七: 看起来不错,建议增加移动端适配

[... more messages grouped by time ...]

总共 24 条消息。需要查看具体某条消息的详情吗?

Important Notes

Permission Boundaries (权限边界)

• Can only access groups the user is a member of
• Cannot read messages from groups the user hasn't joined
• Message sending requires appropriate group permissions
• Some groups may restrict who can send messages

Group Identification (群组识别)

• Groups are identified by chat_id (e.g., oc_xxx123)
• Use group names to search, then get chat_id
• Cache chat_id for frequently accessed groups
• Group names may not be unique - confirm with user if multiple matches

Message Format (消息格式)

• Text messages: Simple string content
• Rich text: JSON with formatting and mentions
• Attachments: Require file_key from upload
• @mentions: Use user's open_id

Rate Limits (速率限制)

• API calls have rate limits per user
• Batch operations when possible
• Use pagination for large result sets
• Monitor for rate limit errors

Error Handling

Common errors and solutions:

1. "Group not found" (群聊未找到)

   • User is not a member of this group
   • Group name may be misspelled
   • Use group list to find exact name

2. "Permission denied" (权限被拒绝)

   • User doesn't have permission to perform this action
   • Check group settings and user role

3. "Message send failed" (消息发送失败)

   • Bot doesn't have send permission in the group
   • Group may be archived or deleted
   • Check message content format

4. "Invalid token" (无效令牌)

   • MCP server authentication failed
   • Verify LARK_APP_ID and LARK_APP_SECRET
   • Ensure OAuth token is valid

Tips for Effective Use

1. Use descriptive group names: When searching, use clear keywords
2. Check before sending: Confirm the correct group before sending messages
3. Respect privacy: Only access messages when necessary
4. Time ranges: Use time filters to narrow down message searches
5. Pagination: For groups with many messages, fetch in batches
6. User IDs: Get user open_id when mentioning specific people

Advanced Features

Thread Messages (话题消息)

• Access threaded replies within messages
• Use container_id_type: "thread" for thread messages
• Thread ID can be obtained from message responses

Message Search (消息搜索)

• While there's no direct search API, you can:
  1. Get message history
  2. Filter locally by keyword
  3. Use time ranges to narrow scope

Group Creation (创建群聊)

• Requires appropriate permissions
• Can specify initial members
• Set group name, description, and settings
• Add bots to the group

Related Skills

• lark-docs: Access Lark cloud documents
• Future: lark-calendar, lark-approval, lark-contacts

Privacy & Security

• All operations use the authenticated user's identity
• Cannot access private conversations without permission
• Message content is only accessible to authorized group members
• Follow company policies for message access and data handling