Feishu/Lark OpenAPI MCP

английский |中文

Извлечение документации разработчика MCP | Официальный документ

⚠️ Уведомление о бета-версии : этот инструмент в настоящее время находится на стадии бета-тестирования. Функции и API могут измениться, поэтому, пожалуйста, следите за выпусками версий.

Это официальный инструмент Feishu/Lark OpenAPI MCP (Model Context Protocol), разработанный для того, чтобы помочь пользователям быстро подключиться к платформе Feishu/Lark и обеспечить эффективное сотрудничество между агентами ИИ и Feishu/Lark. Инструмент инкапсулирует интерфейсы Feishu/Lark Open Platform API как инструменты MCP, позволяя помощникам ИИ напрямую вызывать эти интерфейсы и реализовывать различные сценарии автоматизации, такие как обработка документов, управление разговорами, планирование календаря и многое другое.

Функции

• Полный набор инструментов API Feishu/Lark: инкапсулирует почти все интерфейсы API Feishu/Lark, включая управление сообщениями, управление группами, операции с документами, события календаря, Bitable и другие основные функциональные области.

• Поддержка двойной аутентификации:

  • Поддерживает аутентификацию с помощью токена доступа к приложению

  • Поддерживает аутентификацию с помощью токена доступа пользователя

• Гибкие протоколы связи:

  • Поддерживает стандартный режим потока ввода/вывода (stdio), подходит для интеграции с инструментами ИИ, такими как Trae/Cursor/Claude

  • Поддерживает режим Server-Sent Events (SSE), предоставляя интерфейсы на основе HTTP

• Поддерживает несколько методов настройки, адаптируясь к различным сценариям использования

Related MCP server: Feishu/Lark OpenAPI MCP

Список инструментов

Полный список всех поддерживаемых инструментов Feishu/Lark можно найти на tools.md , где инструменты отсортированы по проектам и версиям с описаниями.

Подготовка

Создание приложения Feishu/Lark

Перед использованием инструмента lark-mcp необходимо создать приложение Feishu/Lark:

1. Посетите Feishu Open Platform или Lark Open Platform и войдите в систему.

2. Нажмите «Консоль» и создайте новое приложение.

3. Получите идентификатор приложения и секретный ключ приложения, которые будут использоваться для аутентификации API.

4. Добавьте необходимые разрешения для вашего приложения в зависимости от вашего сценария использования.

5. Если вам необходимо вызывать API как пользователь, настройте URL-адреса перенаправления OAuth 2.0 и получите токены доступа пользователя.

Подробные инструкции по созданию и настройке приложений см. в документации Feishu Open Platform — Создание приложения или в документации Lark Open Platform .

Установка Node.js

Перед использованием инструмента lark-mcp необходимо установить среду Node.js.

Установка Node.js на macOS

1. Использование Homebrew (рекомендуется) :

   brew install node

2. Использование официального установщика :

   • Посетите сайт Node.js

   • Загрузите и установите версию LTS

   • После установки проверьте в терминале:

     node -v
     npm -v

Установка Node.js на Windows

1. Использование официального установщика :

   • Посетите сайт Node.js

   • Загрузите и запустите установщик Windows (файл .msi)

   • Следуйте указаниям мастера установки для завершения установки.

   • После установки проверьте в командной строке:

     node -v
     npm -v

2. Использование nvm-windows :

   • Скачать nvm-windows

   • Установить nvm-windows

   • Используйте nvm для установки Node.js:

     nvm install latest
     nvm use <version_number>

Установка

Установите инструмент lark-mcp глобально:

npm install -g @larksuiteoapi/lark-mcp

Руководство по использованию

Использование с Trae/Cursor/Claude

Чтобы интегрировать функциональность Feishu/Lark в инструменты искусственного интеллекта, такие как Trae, Cursor или Claude, добавьте в файл конфигурации следующее:

{
  "mcpServers": {
    "lark-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@larksuiteoapi/lark-mcp",
        "mcp",
        "-a",
        "<your_app_id>",
        "-s",
        "<your_app_secret>"
      ]
    }
  }
}

Для доступа к API с использованием идентификатора пользователя вы можете добавить токен доступа пользователя:

{
  "mcpServers": {
    "lark-mcp": {
     "command": "npx",
      "args": [
        "-y",
        "@larksuiteoapi/lark-mcp",
        "mcp",
        "-a",
        "<your_app_id>",
        "-s",
        "<your_app_secret>",
        "-u",
        "<your_user_token>"
      ]
    }
  }
}

Конфигурация пользовательского API

По умолчанию служба MCP включает общие API. Чтобы включить другие инструменты или только определенные API или предустановки, вы можете указать их с помощью параметра -t (через запятую):

lark-mcp mcp -a <your_app_id> -s <your_app_secret> -t im.v1.message.create,im.v1.message.list,im.v1.chat.create,preset.calendar.default

Подробные сведения о предустановленных коллекциях инструментов

В следующей таблице подробно описан каждый инструмент API и его включение в различные коллекции предустановок, что поможет вам выбрать подходящую предустановку для ваших нужд:

Примечание : В таблице "✓" указывает, что инструмент включен в этот пресет. Использование -t preset.xxx включит только инструменты, отмеченные "✓" в соответствующем столбце.

Расширенная конфигурация

Параметры командной строки

Инструмент lark-mcp mcp предоставляет различные параметры командной строки для гибкой настройки службы MCP:

Примеры использования параметров

1. Базовое использование (с использованием идентификатора приложения):

   lark-mcp mcp -a cli_xxxx -s yyyyy

2. Использование идентификатора пользователя :

   lark-mcp mcp -a cli_xxxx -s yyyyy -u u-zzzz

   Примечание : токены доступа пользователя можно получить через процесс авторизации Feishu Open Platform или процесс авторизации Lark Open Platform , или вы можете использовать консоль отладки API для их получения. После использования токена доступа пользователя вызовы API будут выполняться с идентификатором этого пользователя.

3. Настройка определенного режима токена :

   lark-mcp mcp -a cli_xxxx -s yyyyy --token-mode user_access_token

   Примечание : эта опция позволяет явно указать, какой тип токена использовать при вызове API. auto режим (по умолчанию) будет определяться LLM при вызове API.

4. Указание доменов Lark или KA :

   # Lark international version
   lark-mcp mcp -a <your_app_id> -s <your_app_secret> -d https://open.larksuite.com
   
   # Custom domain (KA domain)
   lark-mcp mcp -a <your_app_id> -s <your_app_secret> -d https://open.your-ka-domain.com

5. Включение только определенных инструментов API или других инструментов API :

   lark-mcp mcp -a cli_xxxx -s yyyyy -t im.v1.chat.create,im.v1.message.create

   Примечание : Параметр -t поддерживает следующие предустановленные наборы инструментов:

   • preset.default — набор инструментов по умолчанию, содержащий все предустановленные инструменты

   • preset.im.default — инструменты, связанные с мгновенным обменом сообщениями, такие как управление группами, отправка сообщений и т. д.

   • preset.bitable.default — инструменты, связанные с Bitable, такие как создание таблиц, управление записями и т. д.

   • preset.bitable.batch — инструменты пакетной обработки Bitable, включая функции пакетного создания и обновления записей

   • preset.doc.default — инструменты, связанные с документами, такие как чтение содержимого документа, управление разрешениями и т. д.

   • preset.task.default — инструменты, связанные с управлением задачами, такие как создание задач, управление участниками и т. д.

   • preset.calendar.default — инструменты управления событиями календаря, такие как создание событий календаря, запрос статуса «свободен/занят» и т. д.

6. Использование режима SSE с определенным портом и хостом :

   lark-mcp mcp -a cli_xxxx -s yyyyy -m sse --host 0.0.0.0 -p 3000

7. Установка китайского языка в инструментах :

   lark-mcp mcp -a cli_xxxx -s yyyyy -l zh

   Примечание : Установка языка на китайский ( -l zh ) может потреблять больше токенов. Если вы столкнетесь с проблемами ограничения токенов при интеграции с большими языковыми моделями, рассмотрите возможность использования настройки английского языка по умолчанию ( -l en ).

8. Установка формата имени инструмента на CamelCase :

   lark-mcp mcp -a cli_xxxx -s yyyyy -c camel

   Примечание : Установив формат имени инструмента, вы можете изменить способ отображения имен инструментов в MCP. Например, im.v1.message.create в разных форматах:

   • формат змеи (по умолчанию): im_v1_message_create

   • Формат Camel: imV1MessageCreate

   • Формат кебаба: im-v1-message-create

   • формат точки: im.v1.message.create

9. Использование переменных среды вместо параметров командной строки :

   # Set environment variables
   export APP_ID=cli_xxxx
   export APP_SECRET=yyyyy
   
   # Start the service (no need to specify -a and -s parameters)
   lark-mcp mcp

10. Использование файла конфигурации :

Помимо параметров командной строки, для установки параметров можно также использовать файл конфигурации в формате JSON:

lark-mcp mcp --config ./config.json

Пример файла конфигурации (config.json):

{
  "appId": "cli_xxxx",
  "appSecret": "xxxx",
  "domain": "https://open.feishu.cn",
  "tools": ["im.v1.message.create","im.v1.chat.create"],
  "toolNameCase": "snake",
  "language": "zh",
  "userAccessToken": "",
  "tokenMode": "auto",
  "mode": "stdio",
  "host": "localhost",
  "port": "3000"
}

Примечание : Параметры командной строки имеют более высокий приоритет, чем файл конфигурации. При использовании как параметров командной строки, так и файла конфигурации параметры командной строки переопределят соответствующие настройки в файле конфигурации.

11. Виды транспорта :

lark-mcp поддерживает два режима транспортировки:

1. Режим stdio (по умолчанию/рекомендуется) : подходит для интеграции с инструментами ИИ, такими как Trae/Cursor или Claude, взаимодействующими через стандартные потоки ввода/вывода.

lark-mcp mcp -a <your_app_id> -s <your_app_secret> -m stdio

2. Режим SSE : предоставляет HTTP-интерфейс на основе событий, отправляемых сервером, подходящий для сценариев, где локальное выполнение невозможно.

# Default listens only on localhost
lark-mcp mcp -a <your_app_id> -s <your_app_secret> -m sse -p 3000

# Listen on all network interfaces (allowing remote access)
lark-mcp mcp -a <your_app_id> -s <your_app_secret> -m sse --host 0.0.0.0 -p 3000

После запуска конечная точка SSE будет доступна по адресу http://<host>:<port>/sse .

Часто задаваемые вопросы

• Проблема : Невозможно подключиться к API Feishu/Lark Решение : Проверьте сетевое подключение и убедитесь, что APP_ID и APP_SECRET указаны правильно. Убедитесь, что вы можете получить доступ к API Feishu/Lark Open Platform; возможно, вам придется настроить прокси-сервер.

• Проблема : Ошибка при использовании user_access_token Решение : Проверьте, не истек ли срок действия токена. Обычно срок действия user_access_token составляет 2 часа, и его необходимо периодически обновлять. Вы можете реализовать механизм автоматического обновления токена.

• Проблема : Невозможно вызвать определенные API после запуска службы MCP, с ошибками недостаточного количества разрешений Решение : Проверьте, получило ли ваше приложение соответствующие разрешения API. Некоторые API требуют дополнительных разрешений высокого уровня, которые можно настроить в Developer Console или Lark Developer Console . Убедитесь, что разрешения были одобрены.

• Проблема : Вызовы API, связанные с загрузкой/выгрузкой изображений или файлов, не работают. Решение : Текущая версия не поддерживает функциональность загрузки/выгрузки файлов и изображений. Эти API будут поддерживаться в будущих версиях.

• Проблема : Командная строка отображает искаженные символы в среде Windows Решение : Измените кодировку командной строки на UTF-8, выполнив команду chcp 65001 в командной строке. Если вы используете PowerShell, вам может потребоваться изменить шрифт терминала или конфигурацию PowerShell.

• Проблема : Ошибки разрешений во время установки Решение : На macOS/Linux используйте sudo npm install -g @larksuiteoapi/lark-mcp для установки или измените разрешения глобального пути установки npm. Пользователи Windows могут попробовать запустить командную строку от имени администратора.

• Проблема : превышен лимит токенов после запуска службы MCP. Решение : попробуйте использовать -t , чтобы уменьшить количество включенных API, или используйте модель, которая поддерживает более крупные токены (например, claude3.7).

• Проблема : Невозможно подключиться или получить сообщения в режиме SSE. Решение : Проверьте, не используется ли уже порт, и попробуйте изменить его на другой порт. Убедитесь, что клиент правильно подключен к конечной точке SSE и обрабатывает поток событий.

Ссылки по теме

• Открытая платформа Фейшу

• Открытая международная платформа Lark

• Документация по API открытой платформы Feishu

• Документация API открытой платформы Lark

• Сайт Node.js

• Документация npm

Обратная связь

Вопросы приветствуются, чтобы помочь улучшить этот инструмент. Если у вас есть какие-либо вопросы или предложения, пожалуйста, поднимите их в репозитории GitHub.