lark-hermes-mcp

English · 简体中文

Легковесный MCP stdio-сервер, который предоставляет возможности Feishu (飞书) / Lark в качестве функциональных инструментов для Hermes, Claude Desktop или любого другого MCP-совместимого агента.

• 17 резервных инструментов (написанных вручную) для обмена сообщениями, работы с Bitable, календарем, документами и задачами.

• 36 инструментов, подключенных через @larksuite/openclaw-lark с помощью адаптера-прослойки.

• 4 инструмента OAuth (lark_oauth_start / lark_oauth_complete / lark_oauth_status / lark_oauth_revoke), использующих Device Flow от OpenClaw для авторизации через user-access-token.

Транспорт: stdio (stdout предназначен только для JSON-RPC, логи pino выводятся в stderr) Авторизация: tenant_access_token + user-access-token (OAuth Device Flow) SDK: @larksuiteoapi/node-sdk + @larksuite/openclaw-lark

Требования

• Node.js ≥ 22

• Собственное пользовательское приложение (自建应用) Feishu или Lark

• MCP-совместимый клиент (например, Hermes, Claude Desktop или любой другой stdio MCP-хост)

Related MCP server: Feishu/Lark OpenAPI MCP

Установка

Шаг 1 — Зарегистрируйте свое приложение Feishu / Lark

Этот проект не поставляется с предустановленными учетными данными приложения. Каждый пользователь должен создать свое собственное приложение на открытой платформе Feishu/Lark.

1. Перейдите на https://open.feishu.cn/app (внутри Китая, Feishu) или https://open.larksuite.com/app (за пределами Китая, Lark).

2. Нажмите "创建企业自建应用" / "Create Custom App". Дайте ему имя и выберите иконку.

3. После создания откройте панель управления приложением:

   • Страница 凭证与基础信息 / Credentials & Basic Info → скопируйте ваш App ID (формат cli_xxxxxxxxxxxxxxxx) и App Secret.

   • Страница 权限管理 / Permissions & Scopes → включите области доступа (scopes), которые планируете использовать. Для инструментов, включенных здесь, базовый набор:

     • im:message, im:chat (сообщения)

     • bitable:app (многомерные таблицы)

     • docx:document, drive:drive (документы)

     • calendar:calendar (календарь)

     • Области доступа, связанные с задачами, если вы хотите использовать инструменты для задач.

   • Если вы планируете использовать инструменты OAuth (user-access-token), также включите Device Flow / OAuth в настройках приложения. Инструменты OAuth запрашивают гранулярные области доступа для каждого API во время выполнения — lark_oauth_start выведет точный список областей при первом вызове, чтобы вы знали, что нужно включить.

4. 发布 / Publish версию приложения в панели управления, чтобы изменения областей доступа вступили в силу.

Шаг 2 — Клонирование и установка

git clone https://github.com/WilliamMo101/lark-hermes-mcp.git
cd lark-hermes-mcp
npm install # triggers postinstall patches (see "Upstream & Patches" below)
npm run build

Шаг 3 — Настройка учетных данных

Автономно (любой MCP-хост):

cp .env.example .env
# then edit .env and paste the App ID / App Secret you got in Step 1

Файл .env игнорируется git и никогда не будет закоммичен.

В Hermes: вам не нужен файл .env. Укажите переменные напрямую в profiles/<your-agent>/config.yaml в разделе mcp_servers.lark.env:

mcp_servers:
 lark:
 command: /path/to/node
 args:
 - /path/to/lark-hermes-mcp/dist/server.js
 env:
 LARK_APP_ID: "cli_xxxxxxxxxxxxxxxx"
 LARK_APP_SECRET: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
 LARK_DOMAIN: "Feishu"
 LARK_ENABLED_TOOLSETS: "messaging,docs,bitable,calendar,other"
 LARK_LOG_LEVEL: "info"
 timeout: 120
 connect_timeout: 30
 tools:
 resources: false
 prompts: false

LARK_DOMAIN: для Feishu в материковом Китае → Feishu; для международного Lark → Lark. Неверное значение будет отклонено сервисом OAuth (invalid_client).

LARK_ENABLED_TOOLSETS должен включать other, если вы хотите, чтобы инструменты OAuth (lark_oauth_*) и инструменты для задач были доступны.

Шаг 4 — Запуск и проверка

node dist/server.js # starts the stdio MCP server

Или подключите его к вашему MCP-хосту и вызовите feishu_get_user или lark_oauth_status в качестве дымового теста.

Hermes предоставляет инструменты с префиксом mcp_lark_<name> (подчеркивания, согласно mcp_tool.py:sanitize_mcp_name_component).

Примеры путей в этом README (например, /root/.hermes/mcp-servers/… в старых фрагментах) отражают структуру Hermes-on-WSL автора. Адаптируйте их под место, куда вы клонировали репозиторий.

Резервные инструменты (17)

Это спецификации, написанные вручную в src/adapter/fallback.ts:

Инструменты, подключенные через OpenClaw (36)

src/adapter/shim.ts вызывает registerXxxTools(api) для внутренних регистраций @larksuite/openclaw-lark, оборачивает каждый инструмент с помощью typebox → преобразование в JSON Schema (для совместимости с вызовом функций OpenAI) и внедряет контекст withTicket через AsyncLocalStorage.

Инструменты появляются с префиксом feishu_ / mcp_doc_, например, feishu_bitable_app, feishu_calendar_event, feishu_im_chat_messages.

Инструменты OAuth (4)

• lark_oauth_start — начало Device Flow (выводит user_code + URL для верификации)

• lark_oauth_complete — опрос токена после того, как пользователь авторизуется в браузере

• lark_oauth_status — проверка статуса сохраненного токена пользователя (valid / needs_refresh / expired)

• lark_oauth_revoke — отзыв сохраненного токена пользователя

Токены шифруются (AES-256-GCM) и хранятся в ~/.local/share/openclaw-feishu-uat/.

Дымовой тест (автономно, без MCP-хоста)

export LARK_APP_ID=cli_xxx LARK_APP_SECRET=xxx LARK_DOMAIN=Feishu
(
 echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}'
 echo '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}'
 echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
 echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"selfCheck","arguments":{}}}'
) | node dist/server.js 2>/tmp/lark-mcp.err > /tmp/lark-mcp.out
jq '.result.tools | length' < /tmp/lark-mcp.out
jq 'select(.id==3)' < /tmp/lark-mcp.out

Также существует дымовой тест количества регистраций для прослойки:

LARK_APP_ID=cli_xxx node scripts/shim-smoke.mjs

Upstream и патчи

Этот проект построен на базе @larksuite/openclaw-lark (лицензия MIT) — 36 из представленных инструментов подключены напрямую из его собственных регистраций через src/adapter/shim.ts.

scripts/postinstall-patches.mjs запускается автоматически после npm install и применяет идемпотентные патчи внутри node_modules/@larksuite/openclaw-lark/, чтобы пакет корректно загружался в Node 22 CJS:

1. Удаление синтаксиса import.meta.url из version.js (заменено на разрешение на основе createRequire).

2. Аналогичная обработка для token-store.js.

3. Создание минимальной заглушки для @openclaw/plugin-sdk (только те части, которые реально импортируются).

4. Расширение карты exports пакета, чтобы глубокие импорты ./src/* разрешались.

Эти патчи изменяют только файлы внутри вашего локального node_modules/. Исходный код upstream не изменяется, и патчи безопасно перезапускаются при каждой установке.

Устранение неполадок

• Ничего нет в списке инструментов хоста — выполните grep лога хоста по запросу MCP server 'lark'. Распространенные причины:

  • LARK_APP_ID / LARK_APP_SECRET не переданы — переменные окружения оболочки не распространяются, если хост использует список разрешенных переменных. Объявите их в блоке конфигурации MCP.

  • Отсутствует dist/server.js — выполните npm run build.

  • Неверный бинарный файл node — должна быть версия Node ≥ 22.

• Инструменты OAuth отсутствуют в списке — LARK_ENABLED_TOOLSETS должен включать other.

• invalid_scope в lark_oauth_start — одна из запрошенных областей доступа еще не предоставлена вашему приложению. Откройте страницу разрешений приложения, включите области, указанные в ошибке, и опубликуйте новую версию.

• invalid_client в OAuth — LARK_DOMAIN неверно указан для вашего региона (внутри Китая = Feishu, за пределами = Lark).

• Засорение stdout (MCP-клиент немедленно отключается) — какая-то сторонняя библиотека пишет в stdout. Проверьте логи stderr. server.ts уже перехватывает console.*, а pino пишет в stderr.

• Ограничение скорости на стороне клиента — настройте LARK_THROTTLE_BITABLE_RPS и т.д. через переменные окружения.

Структура проекта

src/
 server.ts # MCP entry, console hijack, handlers
 auth.ts # @larksuiteoapi/node-sdk Client factory
 log.ts # pino → stderr
 toolsets.ts # toolset enum + env filter
 util/throttle.ts # per-toolset token bucket
 adapter/
 index.ts # tool loader + toolset filter
 fallback.ts # 17 hand-written fallback tool specs
 shim.ts # OpenClaw bridge + schema flattening
 oauth-tools.ts # 4 OAuth tools (Device Flow)
scripts/
 postinstall-patches.mjs # idempotent node_modules patches
 shim-smoke.mjs # registration-count smoke test

Благодарности

• @larksuite/openclaw-lark от OpenClaw — лицензия MIT. Этот проект является оберткой и зависит от него.

• Model Context Protocol SDK от Anthropic.

• API открытой платформы Feishu / Lark.

Отказ от ответственности

Это личный хобби-проект, предоставляемый «как есть» без каких-либо гарантий. Он не является официальным продуктом Feishu, Lark, ByteDance или OpenClaw.

这是一个个人兴趣项目，按"现状"提供，不附带任何担保。本项目与飞书/Lark、字节跳动、OpenClaw 官方团队无隶属关系，出现问题请通过 GitHub Issues 反馈。

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• bitableCreateRecordB
• bitableListRecordsC
• bitableUpdateRecordC
• calendarCreateEventC
• calendarListCalendarsC
• calendarListEventsC
• docxGetRawContentC
• docxListBlocksC