feishu-automation

Lark 全チャネル自動化

lark-mcp ツールを使用して、Lark プラットフォームの包括的な自動化操作を実現します。

主な機能

1. Bitable

• Bitable とデータテーブルの作成
• フィールドの追加、変更、削除
• レコードデータの追加、削除、変更、検索
• データの一括インポート／エクスポート
• データのフィルタリングと並べ替え

2. メッセージ送信

• テキスト、リッチテキスト、カードメッセージの送信
• グループメッセージとダイレクトメッセージ
• メッセージテンプレートとインタラクティブカード
• ファイルと画像の送信

3. ドキュメント管理

• クラウドドキュメントの検索
• 新しいドキュメントの作成
• ドキュメント内容の編集
• ドキュメント権限の管理
• ドキュメントの共同編集者の管理

4. グループ管理

• グループの作成
• メンバーの追加／削除
• グループ一覧の取得
• グループ情報の照会

5. ナレッジベース（Wiki）

• ナレッジベースのノードを検索
• ノードの詳細を取得
• ナレッジベースのコンテンツを作成、管理

6. カレンダーとタスク

• カレンダーイベントの作成と検索
• タスクの作成と管理
• タスクの割り当てと追跡

クイックスタート

MCP の利用可否を確認

// 检查 lark-mcp 工具是否可用
// 可用工具前缀：mcp__lark-mcp_

テストメッセージを送信

// 发送文本消息到群组
await mcp__lark-mcp_sendMessage({
  receive_id: "oc_xxxxxxxxx",
  msg_type: "text",
  content: JSON.stringify({
    text: "Hello from Clawdbot!"
  })
});

ワークフロー

データ同期の流れ

1. データソースに接続
2. データ形式を変換
3. Bitable を作成／更新
4. データを一括書き込み
5. 通知を送信

メッセージ配信の流れ

1. イベントをトリガー（定期実行／イベント駆動）
2. メッセージ内容を作成
3. 受信者 ID を取得
4. メッセージを送信
5. ログを記録

ドキュメント自動化の流れ

1. ドキュメントテンプレートを取得
2. 内容を入力
3. 新しいドキュメントを作成
4. 権限を設定
5. チームに共有

API ツールリファレンス

Bitable 関連

• createBitable - Bitable を作成
• createTable - データテーブルを作成
• addRecord - レコードを追加
• updateRecord - レコードを更新
• deleteRecord - レコードを削除
• searchRecords - レコードを検索
• getRecord - レコードの詳細を取得

メッセージ関連

• sendMessage - メッセージを送信
• getMessages - メッセージ履歴を取得
• replyMessage - メッセージに返信

ドキュメント関連

• searchDocs - ドキュメントを検索
• createDoc - ドキュメントを作成
• getDoc - ドキュメント内容を取得
• updateDoc - ドキュメントを更新
• setDocPermission - ドキュメント権限を設定

📄 Markdown をクラウドドキュメントにインポート（推奨方法）

ベストプラクティス：ローカルの Markdown ファイルを直接 Lark クラウドドキュメントにインポートすると、書式が完全に保持されます。

# 1. 获取 access_token
TOKEN=$(curl -s -X POST 'https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal' \
  -H 'Content-Type: application/json' \
  -d '{"app_id":"YOUR_APP_ID","app_secret":"YOUR_APP_SECRET"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin).get('tenant_access_token',''))")

# 2. 上传 md 文件到飞书云盘
FILE_TOKEN=$(curl -s -X POST 'https://open.feishu.cn/open-apis/drive/v1/files/upload_all' \
  -H "Authorization: Bearer $TOKEN" \
  -F "file_name=document.md" \
  -F "parent_type=explorer" \
  -F "parent_node=" \
  -F "size=$(stat -c%s /path/to/document.md)" \
  -F "file=@/path/to/document.md" \
  | python3 -c "import sys,json; print(json.load(sys.stdin).get('data',{}).get('file_token',''))")

# 3. 导入为飞书云文档
TICKET=$(curl -s -X POST 'https://open.feishu.cn/open-apis/drive/v1/import_tasks' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "file_extension": "md",
    "file_token": "'"$FILE_TOKEN"'",
    "type": "docx",
    "point": {"mount_type": 1, "mount_key": ""}
  }' | python3 -c "import sys,json; print(json.load(sys.stdin).get('data',{}).get('ticket',''))")

# 4. 等待导入完成，获取文档链接
sleep 2
curl -s -X GET "https://open.feishu.cn/open-apis/drive/v1/import_tasks/$TICKET" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('data',{}).get('result',{}).get('url',''))"

対応しているインポート形式：

• md → Markdown
• docx → Word ドキュメント
• xlsx → Excel シート

注意事項：

• インポートは非同期操作です。結果を取得するには import_tasks/{ticket} をポーリングする必要があります
• mount_type: 1 は「マイスペース」へのインポートを示します
• インポート後のドキュメント URL の形式：https://xxx.feishu.cn/docx/{token}

📤 クラウドドキュメントの完全な出力手順（標準操作）

クラウドドキュメントを出力する際は、毎回以下の手順を完了する必要があります：

1. ローカルの Markdown ファイルを生成
2. Lark ドライブにアップロード → drive/v1/files/upload_all
3. クラウドドキュメントとしてインポート → drive/v1/import_tasks
4. 権限を組織内で編集可能に設定 → drive/v1/permissions/{token}/public
5. リンクを対象のグループに送信

# 完整流程脚本
TOKEN=$(curl -s -X POST 'https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal' \
  -H 'Content-Type: application/json' \
  -d '{"app_id":"APP_ID","app_secret":"APP_SECRET"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin).get('tenant_access_token',''))")

# 1. 上传文件
FILE_TOKEN=$(curl -s -X POST 'https://open.feishu.cn/open-apis/drive/v1/files/upload_all' \
  -H "Authorization: Bearer $TOKEN" \
  -F "file_name=document.md" \
  -F "parent_type=explorer" \
  -F "parent_node=" \
  -F "size=$(stat -c%s document.md)" \
  -F "[email protected]" \
  | python3 -c "import sys,json; print(json.load(sys.stdin).get('data',{}).get('file_token',''))")

# 2. 导入为云文档
TICKET=$(curl -s -X POST 'https://open.feishu.cn/open-apis/drive/v1/import_tasks' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file_extension":"md","file_token":"'"$FILE_TOKEN"'","type":"docx","point":{"mount_type":1,"mount_key":""}}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin).get('data',{}).get('ticket',''))")

sleep 2

# 3. 获取文档 token
DOC_RESULT=$(curl -s -X GET "https://open.feishu.cn/open-apis/drive/v1/import_tasks/$TICKET" \
  -H "Authorization: Bearer $TOKEN")
DOC_TOKEN=$(echo "$DOC_RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('data',{}).get('result',{}).get('token',''))")
DOC_URL=$(echo "$DOC_RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('data',{}).get('result',{}).get('url',''))")

# 4. 设置权限：组织内可编辑
curl -s -X PATCH "https://open.feishu.cn/open-apis/drive/v1/permissions/$DOC_TOKEN/public?type=docx" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"external_access_entity":"open","security_entity":"anyone_can_view","comment_entity":"anyone_can_view","share_entity":"anyone","link_share_entity":"tenant_editable"}'

# 5. 发送到群
curl -s -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"receive_id":"CHAT_ID","msg_type":"text","content":"{\"text\":\"📄 文档已上传：\\n\\n'"$DOC_URL"'\"}"}'

権限設定の説明：

• link_share_entity: "tenant_editable" → 組織内でリンクを取得した人が編集できます
• comment_entity: "anyone_can_view" → 誰でもコメントできます
• share_entity: "anyone" → 誰でも共有できます

グループ関連

• createGroup - グループを作成
• addMember - メンバーを追加
• getGroupList - グループ一覧を取得
• getGroupInfo - グループ情報を取得

活用シーン

1. 日報収集の自動化

• 毎日定刻にテーブルレコードを作成
• メンバーが日報を記入
• 統計を自動集計
• グループに送信

2. 承認ワークフロー

• 承認用テーブルを作成
• 状態の変更を監視
• 承認者に自動通知
• 承認履歴を記録

3. タスク管理

• タスクテーブルを作成
• メンバーにタスクを割り当て
• タスクのリマインダーを送信
• 完了状況を追跡

4. 顧客管理

• 顧客情報テーブル
• フォローアップ記録
• 自動リマインダー
• データの可視化

5. レポート生成

• テーブルからデータを抽出
• 統計レポートを生成
• Lark ドキュメントを作成
• 定期的に更新情報を配信

ベストプラクティス

認証設定

• 提供された App ID と App Secret を使用
• API 呼び出し頻度の制限を遵守
• access_token をキャッシュ

データ操作

• 一括操作ではページネーションを使用
• データを書き込む前に形式を検証
• エラー処理と再試行を実装
• 操作ログを記録

メッセージ送信

• インタラクティブカードを使用して利便性を向上
• 送信頻度を適切に管理
• 機密情報の送信を避ける
• ユーザー操作に対応

権限管理

• 最小権限の原則
• 権限を定期的に確認
• 共同編集者のライフサイクルを管理

エラー処理

よくあるエラー

• 権限不足 - アプリの権限設定を確認
• レート制限エラー - 再試行と待機を実装
• 無効な ID - ユーザー／グループ ID の形式を検証
• ネットワークエラー - 再試行の仕組みを実装

再試行戦略

• 指数バックオフアルゴリズム
• 最大再試行回数の制限
• 失敗したリクエストを記録
• 管理者に通知

セキュリティに関する注意事項

• App Secret を保護する
• ログに機密情報を記録しない
• 環境変数を使用して認証情報を管理する
• アクセストークンを定期的にローテーションする
• データプライバシー規制を遵守する

コード例

Bitable を作成してデータを追加

// 创建多维表格
const bitable = await mcp__lark-mcp_createBitable({
  name: "项目管理",
  folder_token: "folder_token"
});

// 创建数据表
const table = await mcp__lark-mcp_createTable({
  app_token: bitable.app_token,
  table: {
    name: "任务列表",
    fields: [
      { field_name: "任务名称", type: 1 },
      { field_name: "负责人", type: 13 },
      { field_name: "状态", type: 3 },
      { field_name: "截止日期", type: 5 }
    ]
  }
});

// 添加记录
await mcp__lark-mcp_addRecord({
  app_token: bitable.app_token,
  table_id: table.table_id,
  fields: {
    "任务名称": "完成项目文档",
    "负责人": "user_id",
    "状态": "进行中",
    "截止日期": Date.now()
  }
});

カードメッセージを送信

await mcp__lark-mcp_sendMessage({
  receive_id: "chat_id",
  msg_type: "interactive",
  content: JSON.stringify({
    config: {
      wide_screen_mode: true
    },
    header: {
      template: "turquoise",
      title: {
        content: "重要通知",
        tag: "plain_text"
      }
    },
    elements: [
      {
        tag: "div",
        text: {
          content: "**项目里程碑已完成**",
          tag: "lark_md"
        }
      },
      {
        tag: "action",
        actions: [
          {
            tag: "button",
            text: {
              content: "查看详情",
              tag: "plain_text"
            },
            type: "primary",
            url: "https://example.com"
          }
        ]
      }
    ]
  })
});

データを一括インポート

const data = [
  { name: "张三", phone: "13800138000" },
  { name: "李四", phone: "13900139000" }
];

for (const item of data) {
  await mcp__lark-mcp_addRecord({
    app_token: "app_token",
    table_id: "table_id",
    fields: {
      "姓名": item.name,
      "电话": item.phone
    }
  });

  // 避免限流
  await new Promise(resolve => setTimeout(resolve, 100));
}

設定の検証

MCP サーバーを確認

# 检查 .claude.json 中的 lark-mcp 配置
cat ~/.claude.json | grep -A 15 "lark-mcp"

接続をテスト

// 发送测试消息验证连接
await mcp__lark-mcp_sendMessage({
  receive_id: "your_chat_id",
  msg_type: "text",
  content: JSON.stringify({
    text: "🎉 飞书 MCP 连接成功！"
  })
});

応用的な使い方

Webhook の統合

• Lark の Webhook イベントを監視
• ワークフローを自動でトリガー
• リアルタイムでデータを同期

定期タスクの自動化

• レポートを定期送信
• データを自動バックアップ
• 定期的にクリーンアップ

クロスプラットフォーム連携

• GitHub と連携（Issue の同期）
• メールと連携（通知の配信）
• カレンダーと連携（予定管理）

トラブルシューティング

MCP ツールを利用できない

1. Claude Desktop を再起動
2. ネットワーク接続を確認
3. 認証情報が有効か確認
4. エラーログを確認

API 呼び出しの失敗

1. アプリの権限設定を確認
2. ユーザー／グループ ID を検証
3. レート制限の状態を確認
4. データ形式を確認

権限不足

1. Lark 開発者プラットフォームにログイン
2. アプリの権限範囲を確認
3. 再認証
4. 権限が有効になるまで待機