feishu-integration

Feishu Integration Skill

Comprehensive guide to Feishu (Lark) API integration and automation.

🚀 How It Works

This project providestwo usage methods：

Method 1: MCP Tools (Recommended) ⚡

Real-time interaction, no need to manually run scripts

用户请求 → MCP 工具调用 → 飞书 API → 返回结果

Through the mcp__feishu__* tools, directly operate the Feishu API.

Advantages：

• ✅ Real-time interactive operations
• ✅ No need to switch terminals
• ✅ Automatic authentication handling
• ✅ Supports chained operations

Method 2: Python Scripts 📜

Suitable for complex batch operations and automation workflows.

---

🔧 MCP Tool List

Authentication and Connection

Tool	Function	Use Case
mcp__feishu__get_tenant_access_token	Get access token	Verify connection status

Bitable Management

Tool	Function	Parameters
mcp__feishu__create_bitable	Create Bitable	name: Table namefolder_token: Folder (optional)
mcp__feishu__get_tables	Get data table list	app_token: App token
mcp__feishu__add_table_field	Add field	app_token, table_id, field_name, field_type

Data Operations

Tool	Function	Parameters
mcp__feishu__add_record	Add record	app_token, table_id, fields (dict)
mcp__feishu__get_records	Get records	app_token, table_id, page_size (default 20)

Permission Management

Tool	Function	Parameters
mcp__feishu__add_collaborator	Add collaborator	app_token, member_type, member_id, perm_type
mcp__feishu__get_user_by_email	Find user by email	email: User email

Resource

Resource URI	Function
feishu://config	Get current configuration information

---

💡 Typical Use Cases

Scenario 1: Create different types of Bitable

You are a Bitable creation expert and need to complete the task according to the following steps:

用户请求示例：
- "创建一个客户管理系统"
- "帮我做一个项目任务管理表"
- "建立一个库存管理表格"

助手执行流程：

1. 分析用户需求，设计合理的表格结构
   - 识别业务类型（CRM/项目管理/库存/销售等）
   - 确定核心实体和属性
   - 设计字段关系和数据流

2. 调用 create_bitable 创建多维表格

3. 获取返回的 app_token

4. 调用 get_tables(app_token) 获取 table_id

5. 调用 add_table_field() 添加字段：[根据需求动态生成]
   - 主表：核心业务字段
   - 字段类型选择（文本/数字/日期/单选/多选/人员等）
   - 必填字段和默认值设置

6. 设置字段类型、选项、验证规则
   - 单选字段：配置选项列表
   - 数字字段：设置范围限制
   - 日期字段：配置时间格式
   - 关联字段：建立表间关系

7. 添加示例数据

8. 添加用户为协作者

9. 创建关联表（如需要）
   - 子表设计（如订单明细、任务评论）
   - 表间关联配置
   - 数据关系说明

Example: Create a customer management system

用户: 创建一个客户管理系统

助手执行：

1. 分析需求
   - 业务类型：CRM 客户管理
   - 核心实体：客户、跟进记录
   - 数据流：客户信息 → 跟进互动 → 成交转化

2. 调用 create_bitable(name="客户管理系统")

3. 获取返回的 app_token（例如：app_xxxxxxxxx）

4. 调用 get_tables(app_token) 获取 table_id（例如：tblxxxxxxxx）

5. 调用 add_table_field() 添加字段：
   - 客户名称（field_name="客户名称", field_type=1）文本
   - 联系人姓名（field_name="联系人姓名", field_type=1）文本
   - 联系电话（field_name="联系电话", field_type=11）电话
   - 客户来源（field_name="客户来源", field_type=3）单选
   - 客户阶段（field_name="客户阶段", field_type=3）单选
   - 所属行业（field_name="所属行业", field_type=3）单选
   - 预估成交金额（field_name="预估成交金额", field_type=2）数字
   - 创建时间（field_name="创建时间", field_type=5）日期
   - 备注（field_name="备注", field_type=1）文本

6. 设置字段配置
   - 客户来源选项：网络推广/客户介绍/展会/主动开发
   - 客户阶段选项：潜在客户/意向客户/谈判中/已成交/已流失
   - 所属行业选项：互联网/金融/制造/零售/其他
   - 预估金额：设置最小值为0

7. 添加示例数据
   调用 add_record(app_token, table_id, {
     "客户名称": "示例科技公司",
     "联系人姓名": "张三",
     "联系电话": "13800138000",
     "客户来源": "网络推广",
     "客户阶段": "意向客户",
     "所属行业": "互联网",
     "预估成交金额": 50000,
     "创建时间": 1704067200000,
     "备注": "潜在优质客户"
   })

8. 添加用户为协作者
   调用 get_user_by_email(email="user@example.com") 获取 open_id
   调用 add_collaborator(app_token, "user", open_id, "edit")

9. 创建关联表"跟进记录"
   重复步骤 4-5，创建跟进记录表，包含：
   - 跟进时间（field_type=5）
   - 跟进方式（field_type=3，选项：电话/微信/邮件/面谈）
   - 跟进内容（field_type=1）
   - 下次跟进时间（field_type=5）
   - 客户名称（关联字段，关联到客户信息表）

10. 返回结果
   - 表格链接：https://feishu.cn/base/{app_token}
   - 字段说明文档
   - 使用建议

Example: Create a project task management table

用户: 创建一个项目任务管理表

助手执行：

1. 分析需求
   - 业务类型：项目管理
   - 核心实体：项目、任务
   - 数据流：项目分解 → 任务分配 → 执行跟踪

2. 调用 create_bitable(name="项目任务管理系统")

3. 获取返回的 app_token

4. 调用 get_tables(app_token) 获取 table_id

5. 调用 add_table_field() 为"项目列表"表添加字段：
   - 项目名称（field_name="项目名称", field_type=1）
   - 项目编号（field_name="项目编号", field_type=1）
   - 项目状态（field_name="项目状态", field_type=3）选项：未开始/进行中/已完成/已延期
   - 开始日期（field_name="开始日期", field_type=5）
   - 结束日期（field_name="结束日期", field_type=5）
   - 项目优先级（field_name="项目优先级", field_type=3）选项：高/中/低
   - 项目进度（field_name="项目进度", field_type=15）0-100%
   - 项目经理（field_name="项目经理", field_type=1）

6. 添加示例数据
   调用 add_record() 添加 2-3 个示例项目

7. 添加用户为协作者

8. 创建"任务列表"关联表
   - 任务名称（field_type=1）
   - 所属项目（关联字段 → 项目列表）
   - 任务负责人（field_type=1）
   - 任务状态（field_type=3）选项：待办/进行中/已完成/已取消
   - 任务优先级（field_type=3）选项：紧急/高/中/低
   - 开始时间（field_type=5）
   - 截止时间（field_type=5）
   - 预计工时（field_type=2）
   - 实际工时（field_type=2）
   - 任务描述（field_type=1）

9. 返回双表结构说明、关联关系图、使用建议

Example: Create a purchase order management system

用户: 创建一个采购订单管理系统

助手执行：

1. 分析需求
   - 业务类型：采购管理
   - 核心实体：采购订单
   - 数据流：订单创建 → 审批 → 执行

2. 调用 create_bitable(name="采购订单管理系统")

3. 获取返回的 app_token

4. 调用 get_tables(app_token) 获取 table_id

5. 调用 add_table_field() 添加字段：
   - 采购订单（field_name="采购订单", field_type=1）
   - 采购单价（field_name="采购单价", field_type=2）
   - 采购数量（field_name="采购数量", field_type=2）
   - 采购金额（field_name="采购金额", field_type=2）
   - 采购时间（field_name="采购时间", field_type=5）
   - 采购人（field_name="采购人", field_type=1）

6. 添加示例数据
7. 添加用户为协作者
8. 返回表格链接和使用说明

Scenario 2: Batch import data

用户: 向表格 xyz 添加 10 条采购记录

助手:
1. 调用 get_tables(app_token) 确认 table_id
2. 循环调用 add_record() 添加数据
3. 返回添加结果

Scenario 3: Permission management

用户: 添加 user@example.com 为表格管理员

助手:
1. 调用 get_user_by_email(email="user@example.com") 获取 open_id
2. 调用 add_collaborator(
   app_token="...",
   member_type="user",
   member_id="<open_id>",
   perm_type="full_access"
)

---

🤖 Intelligent Table Type Recognition

Supports recognition of the following business types:

Business Type	Keywords	Preset Fields
Customer Management	CRM, customer, sales, customer management	Customer name, contact, stage, amount
Project Management	Project, task, project task	Project name, status, owner, progress
Procurement Management	Procurement, order, supplier	Order number, unit price, quantity, amount
Inventory Management	Inventory, warehouse, product	Product name, SKU, inventory quantity, location
Personnel Management	Employees, Attendance, Recruitment	Name, Department, Position, Status
Expense Management	Reimbursement, Expenses, Approval	Reimburser, Amount, Type, Date

---

📋 Field Type Description

Type Value	Type Name	Description
1	text	Text
2	number	Number
3	select	Single Select
4	multiSelect	Multi Select
5	dateTime	Date
7	attachment	Attachment
11	phone	Phone
12	email	Email
13	url	URL
15	progress	Progress

---

🔐 Permission Type Description

• view - View Only
• edit - Edit Permission
• full_access - Full Management Permission

---

📁 Project Structure

feishu-integration/
├── plugin.json              # 插件清单
├── SKILL.md                 # 本文档
├── mcp-server/              # MCP 服务器
│   ├── index.py             # FastMCP 实现
│   ├── requirements.txt     # Python 依赖
│   └── README.md            # MCP 文档
├── scripts/                 # Python 脚本（备用）
│   ├── create_feishu_app.py
│   ├── create_purchase_order_bitable.py
│   ├── add_feishu_collaborator.py
│   └── ...
└── .mcp.json                # MCP 配置

---

🛠️ Configuration Description

MCP Server Configuration

Ensure ~/.minto/config/mcp.json contains:

{
  "mcpServers": {
    "feishu": {
      "command": "python3.11",
      "args": ["/path/to/mcp-server/index.py"],
      "env": {
        "FEISHU_APP_ID": "your_app_id",
        "FEISHU_APP_SECRET": "your_app_secret"
      }
    }
  }
}

Environment Variables

• FEISHU_APP_ID: Feishu App ID
• FEISHU_APP_SECRET: Feishu App Secret

How to Obtain:

1. Visit https://open.feishu.cn
2. Create an app or select an existing app
3. Obtain it on the "Credentials & Basic Info" page

---

🔍 Troubleshooting

MCP Tools Unavailable

1. Check whether the MCP server is started:

   minto mcp list
   

2. Check whether the environment variables are configured:

   minto mcp get feishu
   

3. View the MCP configuration file:

   cat ~/.minto/config/mcp.json
   

API Returns 404

• Ensure the relevant permissions are enabled on the Feishu Open Platform
• Republish the app and wait for the permissions to take effect (about 10 minutes)

Failed to Add Collaborator

The app requires the following permissions:

• permission:permission.member.create
• Or permission package: "Share Cloud Documents"

---

📚 Python Script Usage (Alternative)

If you need to use the script method:

cd scripts
python3 create_feishu_app.py
python3 add_feishu_collaborator.py

Dependency Installation:

pip install requests lark-oapi

---

✅ Best Practices

1. Prefer using MCP toolsfor interactive operations
2. Use scripts for batch operationsto improve efficiency
3. After creating a table,add yourself as a collaborator in time
4. Verify permissions: First use get_tenant_access_token to test the connection
5. Save app_token: The token of the created table needs to be saved for subsequent operations

---

🔗 Reference Documentation

• Feishu Open Platform
• Bitable API
• Permission Management API

---

💻 Developer

• GitHub: https://github.com/Within-7/minto-plugin-tools
• MCP Server: FastMCP 2.12.2
• Python: 3.11+