Lark MCP (Feishu Integration)

⚠️ Must-read: Top 5 Key Rules + Important Experiences

Important Experience: Create Resources Using User Identity

yaml

# ⭐ Key: Use useUAT: true to create resources accessible by users
useUAT: true   # ✅ User identity - Creator = current user, you can access directly
useUAT: false  # ❌ Tenant identity - Creator = Feishu Assistant, you cannot access directly

Experience Summary (From Actual Testing):

Bitable Creation Permission Issue - Bases created with useUAT: false have "Feishu Assistant" as the creator, and the current user cannot access them
External Email Permission Restriction - Adding external email permissions via API will fail (error code 1063001)
Solution - Create resources using useUAT: true, and the creator automatically gets full_access permission
Document Permissions - The same applies, create documents using user identity

1. Server Name Must Be Exact

bash

✅ mcp__lark-mcp__tool_name
❌ mcp__lark_mcp__ (Error: underscore)
❌ lark-mcp__ (Error: missing prefix)

2. Nested Parameter Structure

yaml

path:           # URL path parameters (required)
  app_token: ...
  table_id: ...
params:         # URL query parameters (optional)
  user_id_type: "open_id"
data:           # Request body (optional)
  fields: {...}
useUAT: false   # Use tenant token by default

3. Message content Must Be a String

bash

❌ content: {"text": "hello"}
✅ content: '{"text": "hello"}'

4. Filter Condition value Must Be an Array

bash

❌ value: "Completed"
✅ value: ["Completed"]

5. ID Types Cannot Be Confused

open_id   - User ID (recommended)
chat_id   - Group chat ID
app_token - Bitable app ID
table_id  - Table ID
record_id - Record ID

Quick Start

Example 1: Query Bitable Records

yaml

Tool: mcp__lark-mcp__bitable_v1_appTableRecord_search
path:
  app_token: "your_app_token"  # Replace with actual Base app ID (obtained from URL)
  table_id: "your_table_id"    # Replace with actual table ID (obtained from URL)
params:
  page_size: 20
data:
  filter:
    conjunction: "and"
    conditions:
      - field_name: "Status"
        operator: "is"
        value: ["Completed"]

Example 2: Send Text Message to Group

yaml

Tool: mcp__lark-mcp__im_v1_message_create
data:
  receive_id: "oc_xxxxx"  # Replace with actual group chat_id
  msg_type: "text"
  content: '{"text": "Message content"}'
params:
  receive_id_type: "chat_id"

Example 3: Search Documents

yaml

Tool: mcp__lark-mcp__docx_builtin_search
data:
  search_key: "Keywords"
  count: 10
useUAT: true

Tool Categories

Bitable

```
bitable_v1_app_create
```
- Create Base app
```
bitable_v1_appTable_list
```
- List all tables
```
bitable_v1_appTable_create
```
- Create new table
```
bitable_v1_appTableField_list
```
- Get field list
```
bitable_v1_appTableRecord_search
```
- Query records
```
bitable_v1_appTableRecord_create
```
- Create records
```
bitable_v1_appTableRecord_update
```
- Update records

Detailed Guide: reference/bitable.md

Messages

```
im_v1_message_create
```
- Send messages
```
im_v1_message_list
```
- Get chat history
```
im_v1_chat_create
```
- Create groups
```
im_v1_chat_list
```
- Get group list
```
im_v1_chatMembers_get
```
- Get group members

Detailed Guide: reference/messages.md

Documents

```
docx_builtin_search
```
- Search documents
```
docx_builtin_import
```
- Import documents
```
docx_v1_document_rawContent
```
- Get document content

Detailed Guide: reference/documents.md

Groups

```
im_v1_chat_create
```
- Create groups
```
im_v1_chatMembers_get
```
- Get member list
```
im_v1_chat_list
```
- Get group list

Detailed Guide: reference/groups.md

Permissions

```
drive_v1_permissionMember_create
```
- Add collaborator permissions

Detailed Guide: reference/permissions.md

Contacts

```
contact_v3_user_batchGetId
```
- Get user ID via email/phone number

Wiki

```
wiki_v1_node_search
```
- Search Wiki nodes
```
wiki_v2_space_getNode
```
- Get node information

Authentication Instructions

Token Types

useUAT: true - User access token (user operations)
useUAT: false - Tenant access token (backend operations, default)

Obtain IDs

Obtain from URL:

https://xxx.feishu.cn/base/appxxxxx?table=tblxxxxx
                         ↑app_token    ↑table_id

Get user open_id:

yaml

Tool: mcp__lark-mcp__contact_v3_user_batchGetId
data:
  emails: ["user@example.com"]  # Replace with actual user email
params:
  user_id_type: "open_id"

user_id_type Parameter

Always use

"open_id"

(most universal, recommended).

Optional values:

"open_id"

"union_id"

"user_id"

Core Workflows

Workflow 1: Create Bitable and Add Records (User-accessible Version)

Task Progress:
- [ ] Step 1: Create Base app (⭐ useUAT: true)
- [ ] Step 2: Create table and fields
- [ ] Step 3: Insert records
- [ ] Step 4: Verify data

Step 1: Create Base app

yaml

Tool: mcp__lark-mcp__bitable_v1_app_create
data:
  name: "Project Management"  # Can be modified to your required name
  time_zone: "Asia/Shanghai"
useUAT: true  # ⭐ Important: Use user identity to ensure direct access

Step 2: Create Table and Fields

yaml

Tool: mcp__lark-mcp__bitable_v1_appTable_create
path:
  app_token: "bascnxxxxxx"  # Replace with actual app_token returned from Step 1
data:
  table:
    name: "Table Name"
    default_view_name: "Default View"
    fields:
      - field_name: "Name"
        ui_type: "Text"
      - field_name: "Age"
        ui_type: "Number"
      - field_name: "Status"
        ui_type: "SingleSelect"
        property:
          options:
            - name: "In Progress"
            - name: "Completed"

Note: After successful creation, the response will return

table_id

, save it for the next step.

Step 3: Insert Records

yaml

Tool: mcp__lark-mcp__bitable_v1_appTableRecord_create
path:
  app_token: "bascnxxxxxx"  # Replace with actual value returned from Step 1
  table_id: "tblxxxxxx"     # Replace with actual value returned from Step 2
data:
  fields:
    Name: "Zhang San"
    Age: 25
    Status: "In Progress"

Step 4: Verify Data

yaml

Tool: mcp__lark-mcp__bitable_v1_appTableRecord_search
path:
  app_token: "bascnxxxxxx"  # Replace with actual app_token
  table_id: "tblxxxxxx"     # Replace with actual table_id
params:
  page_size: 10

Workflow 2: Query Table and Send Messages

Task Progress:
- [ ] Step 1: Query table data
- [ ] Step 2: Process query results
- [ ] Step 3: Construct message
- [ ] Step 4: Send to group

Step 1: Query Data

yaml

Tool: mcp__lark-mcp__bitable_v1_appTableRecord_search
path:
  app_token: "bascnxxxxxx"  # Replace with actual app_token
  table_id: "tblxxxxxx"     # Replace with actual table_id
params:
  page_size: 10
data:
  filter:
    conjunction: "and"
    conditions:
      - field_name: "Status"
        operator: "is"
        value: ["Pending"]

Step 2: Process Query Results

After successful query, the response contains the

data.items

array, each item includes the record's

fields

yaml

# Example Response Structure
data:
  items:
    - record_id: "recxxxx"
      fields:
        Task Name: "Complete Document"
        Status: "Pending"

Step 3: Construct Message

Construct message content based on query results:

yaml

# Example: Construct text message
message = "Found " + items.length + " pending tasks:\n"
for each item in items:
  message += "- " + item.fields["Task Name"] + "\n"

Step 4: Send Message

yaml

Tool: mcp__lark-mcp__im_v1_message_create
data:
  receive_id: "oc_xxxxx"  # Replace with actual group chat_id
  msg_type: "text"
  content: '{"text": "Processing results: ..."}'
params:
  receive_id_type: "chat_id"

Workflow 3: Search Documents and Get Content

Task Progress:
- [ ] Step 1: Search documents
- [ ] Step 2: Get document_id
- [ ] Step 3: Extract document content
- [ ] Step 4: Process text

Step 1: Search

yaml

Tool: mcp__lark-mcp__docx_builtin_search
data:
  search_key: "Project Report"
  count: 10
useUAT: true

Step 2: Get document_id

After successful search, extract the

document_id

of the first document from the response:

yaml

# Example Response Structure
data:
  items:
    - document_id: "doxcnxxxxxx"  # ← Save this
      title: "Project Report"
      ...

Step 3: Get Content

yaml

Tool: mcp__lark-mcp__docx_v1_document_rawContent
path:
  document_id: "doxcnxxxxxx"  # Replace with actual document_id obtained from Step 2
params:
  lang: 0
useUAT: true

Common Error Troubleshooting

Error 1: "tool not found"

Cause: Incorrect server name spelling Solution: Ensure to use the

mcp__lark-mcp__

prefix (note the hyphens)

Error 2: "invalid request"

Cause: Incorrect parameter nesting Solution: Check the path/params/data hierarchy; path parameters are usually required

Error 3: "field not found"

Cause: Incorrect field name or wrong ID type Solution:

Confirm that
```
field_name
```
exactly matches the table field name
Confirm using the correct ID type (app_token vs table_id)

Error 4: "permission denied"

Cause: Insufficient permissions or wrong token type Solution:

Check if the app has access permissions for the resource
Use
```
useUAT: true
```
for user operations
Use
```
useUAT: false
```
for backend operations

Error 5: Message Sending Failed

Cause: Incorrect content format or wrong receive_id_type Solution:

content must be a JSON string, not an object
Use
```
receive_id_type: "chat_id"
```
for sending to groups
Use
```
receive_id_type: "open_id"
```
for sending to users

Parameter Verification Checklist

Check before use:

Server name:
```
mcp__lark-mcp__tool_name
```
path parameters are required and correct (app_token, table_id, record_id, etc.)
content is a JSON string (for message-related operations)
value is an array (for filter conditions)
Enumeration values match exactly (user_id_type, operator, etc.)
Correct ID type (open_id vs chat_id vs app_token)
useUAT is set correctly (true for users, false for backend)

Issues Encountered in Practice

Issue 1: Created Base Is Inaccessible

Phenomenon:

Create Base app with
```
useUAT: false
```
Creator shows as "Feishu Assistant"
Current user cannot access directly due to permission restrictions

Solution:

yaml

useUAT: true   # ✅ User identity - Creator = current user, accessible directly
useUAT: false  # ❌ Tenant identity - Requires additional permission settings

Issue 2: API Permission Addition Failed

Phenomenon:

Add email permissions via
```
drive_v1_permissionMember_create
```
Error code: 1063001 (Invalid parameter)
Cannot grant external users access via API

Root Cause:

Resources created with tenant identity have restrictions on API permission additions
External email permissions may not be supported via API operations

Best Practice:

Prioritize creating resources using user identity (
```
useUAT: true
```
)
The creator automatically gets
```
full_access
```
permission
Avoid complex permission configurations later

Issue 3: Field Type Mismatch

Phenomenon:

"field not found" when querying Bitable
Used wrong field ID type

Solution:

yaml

# Get correct IDs from URL (appxxxxx and tblxxxxx are placeholders to replace)
https://xxx.feishu.cn/base/appxxxxx?table=tblxxxxx
                         ↑app_token    ↑table_id

# Get field list to confirm field names before querying
Tool: mcp__lark-mcp__bitable_v1_appTableField_list

Issue 4: Group Owner Identity Problem

Phenomenon:

Create groups with
```
useUAT: true
```
Creator still shows as app robot (app_id)
Message sender
```
sender_type
```
is "app", not "user"

Root Cause:

```
useUAT: true
```
only uses user permissions/tokens for operations
The system-recorded "creator" is always the app itself
This is a design mechanism of Feishu API

Solution:

yaml

# Must explicitly specify owner_id
Tool: mcp__lark-mcp__im_v1_chat_create
data:
  owner_id: "ou_xxxxx"  # Specify user as group owner
  user_id_list: ["ou_xxxxx"]

Note: If

owner_id

is not specified, the group owner defaults to the app robot.

Reference Documents

Bitable Operation Guide
Message Sending Guide
Document Operation Guide
Group Management Guide
Permission Management Guide
Bitable Query Examples
Message Format Examples

lark-mcp

NPX Install

Tags

SKILL.md Content (Chinese)

Lark MCP (Feishu Integration)

⚠️ Must-read: Top 5 Key Rules + Important Experiences

Quick Start

Example 1: Query Bitable Records

Example 2: Send Text Message to Group

Example 3: Search Documents

Tool Categories

Bitable

Messages

Documents

Groups

Permissions

Contacts

Wiki

Authentication Instructions

Token Types

Obtain IDs

user_id_type Parameter

Core Workflows

Workflow 1: Create Bitable and Add Records (User-accessible Version)

Workflow 2: Query Table and Send Messages

Workflow 3: Search Documents and Get Content

Common Error Troubleshooting

Error 1: "tool not found"

Error 2: "invalid request"

Error 3: "field not found"

Error 4: "permission denied"

Error 5: Message Sending Failed

Parameter Verification Checklist

Issues Encountered in Practice

Issue 1: Created Base Is Inaccessible

Issue 2: API Permission Addition Failed

Issue 3: Field Type Mismatch

Issue 4: Group Owner Identity Problem

Reference Documents