lark-hermes-mcp

Englisch · 简体中文

Ein schlanker MCP-stdio-Server, der Feishu (飞书) / Lark-Funktionen als Funktionswerkzeuge für Hermes, Claude Desktop oder jeden anderen MCP-kompatiblen Agenten bereitstellt.

• 17 Fallback-Werkzeuge (manuell erstellt) für Messaging, Bitable, Kalender, Dokumente und Aufgabenoperationen

• 36 Werkzeuge, die von @larksuite/openclaw-lark über einen Shim-Adapter überbrückt werden

• 4 OAuth-Werkzeuge (lark_oauth_start / lark_oauth_complete / lark_oauth_status / lark_oauth_revoke), die den Device Flow von OpenClaw für die Autorisierung von Benutzerzugriffstokens steuern

Transport: stdio (stdout ist nur für JSON-RPC, pino-Logs gehen an stderr) Auth: tenant_access_token + user-access-token (OAuth Device Flow) SDK: @larksuiteoapi/node-sdk + @larksuite/openclaw-lark

Anforderungen

• Node.js ≥ 22

• Eine Feishu- oder Lark-benutzerdefinierte App (自建应用), die Ihnen gehört

• Ein MCP-kompatibler Client (z. B. Hermes, Claude Desktop oder ein beliebiger stdio-MCP-Host)

Related MCP server: Feishu/Lark OpenAPI MCP

Installation

Schritt 1 — Registrieren Sie Ihre eigene Feishu / Lark-App

Dieses Projekt wird nicht mit vorregistrierten App-Anmeldedaten ausgeliefert. Jeder Benutzer muss seine eigene App auf der Feishu/Lark-Open-Plattform erstellen.

1. Gehen Sie zu https://open.feishu.cn/app (inländisch Feishu) oder https://open.larksuite.com/app (überseeisch Lark).

2. Klicken Sie auf "创建企业自建应用" / "Create Custom App". Geben Sie ihr einen Namen und ein Symbol.

3. Öffnen Sie nach der Erstellung das App-Dashboard:

   • Seite 凭证与基础信息 / Credentials & Basic Info → kopieren Sie Ihre App ID (Format cli_xxxxxxxxxxxxxxxx) und App Secret.

   • Seite 权限管理 / Permissions & Scopes → aktivieren Sie die Scopes, die Sie verwenden möchten. Für die hier gebündelten Werkzeuge ist das Kernset:

     • im:message, im:chat (Messaging)

     • bitable:app (多维表格)

     • docx:document, drive:drive (Dokumente)

     • calendar:calendar (Kalender)

     • Aufgabenbezogene Scopes, wenn Sie Aufgabenwerkzeuge wünschen

   • Wenn Sie die OAuth-Werkzeuge (user-access-token) verwenden möchten, aktivieren Sie auch Device Flow / OAuth in Ihren App-Einstellungen. Die OAuth-Werkzeuge fordern zur Laufzeit granulare API-Scopes an — lark_oauth_start gibt beim ersten Aufruf die genaue Liste der Scopes aus, damit Sie wissen, was zu aktivieren ist.

4. 发布 / Veröffentlichen Sie die App-Version im App-Dashboard, damit Ihre Scopes wirksam werden.

Schritt 2 — Klonen und installieren

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

Schritt 3 — Konfigurieren Sie Ihre Anmeldedaten

Eigenständig (jeder MCP-Host):

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

.env wird von git ignoriert und niemals committet.

Unter Hermes: Sie benötigen keine .env-Datei. Fügen Sie die Variablen direkt in profiles/<your-agent>/config.yaml unter mcp_servers.lark.env ein:

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: inländisch Feishu → Feishu; überseeisch Lark → Lark. Der falsche Wert wird vom OAuth-Dienst abgelehnt (invalid_client).

LARK_ENABLED_TOOLSETS muss other enthalten, wenn Sie möchten, dass die OAuth-Werkzeuge (lark_oauth_*) und Aufgabenwerkzeuge bereitgestellt werden.

Schritt 4 — Ausführen und überprüfen

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

Oder verbinden Sie es mit Ihrem MCP-Host und rufen Sie feishu_get_user oder lark_oauth_status als Rauchtest auf.

Hermes stellt die Werkzeuge als mcp_lark_<name> bereit (Unterstriche, gemäß mcp_tool.py:sanitize_mcp_name_component).

Beispielpfade in dieser README (wie /root/.hermes/mcp-servers/… in älteren Snippets) spiegeln das eigene Hermes-auf-WSL-Layout des Autors wider. Passen Sie diese an den Ort an, an den Sie das Repo auschecken.

Fallback-Werkzeuge (17)

Dies sind manuell erstellte Spezifikationen in src/adapter/fallback.ts:

OpenClaw-überbrückte Werkzeuge (36)

src/adapter/shim.ts ruft registerXxxTools(api) gegen die internen Registrierungen von @larksuite/openclaw-lark auf, umschließt jedes Werkzeug mit Typebox → JSON-Schema-Abflachung (für OpenAI-Funktionsaufruf-Kompatibilität) und injiziert den withTicket-Kontext über AsyncLocalStorage.

Werkzeuge erscheinen mit dem Präfix feishu_ / mcp_doc_, z. B. feishu_bitable_app, feishu_calendar_event, feishu_im_chat_messages.

OAuth-Werkzeuge (4)

• lark_oauth_start — Device Flow beginnen (gibt user_code + Verifizierungs-URL aus)

• lark_oauth_complete — auf Token abfragen, nachdem der Benutzer im Browser autorisiert hat

• lark_oauth_status — gespeicherten Benutzertoken-Status prüfen (gültig / needs_refresh / abgelaufen)

• lark_oauth_revoke — gespeicherten Benutzertoken widerrufen

Tokens werden verschlüsselt (AES-256-GCM) und unter ~/.local/share/openclaw-feishu-uat/ gespeichert.

Rauchtest (eigenständig, ohne MCP-Host)

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

Es gibt auch einen Registrierungsanzahl-Rauchtest für den Shim:

LARK_APP_ID=cli_xxx node scripts/shim-smoke.mjs

Upstream & Patches

Dieses Projekt baut auf @larksuite/openclaw-lark (MIT-Lizenz) auf — 36 der bereitgestellten Werkzeuge werden direkt aus seinen nativen Werkzeugregistrierungen über src/adapter/shim.ts überbrückt.

scripts/postinstall-patches.mjs wird nach npm install automatisch ausgeführt und wendet idempotente Patches innerhalb von node_modules/@larksuite/openclaw-lark/ an, sodass das Paket unter Node 22 CJS sauber geladen wird:

1. Entfernen der import.meta.url-Syntax aus version.js (ersetzt durch createRequire-basierte Auflösung).

2. Gleiche Behandlung für token-store.js.

3. Erstellen eines minimalen Stubs für @openclaw/plugin-sdk (nur die Teile, die die Registrierungen tatsächlich importieren).

4. Erweitern der exports-Map des Pakets, damit tiefe ./src/*-Importe aufgelöst werden.

Diese Patches ändern nur Dateien innerhalb Ihres lokalen node_modules/. Die Upstream-Quelle wird nicht geändert, und die Patches werden bei jeder Installation sicher erneut ausgeführt.

Fehlerbehebung

• Nichts in der Werkzeugliste des Hosts — durchsuchen Sie das Log des Hosts nach MCP server 'lark'. Häufige Ursachen:

  • LARK_APP_ID / LARK_APP_SECRET nicht weitergegeben — Shell-Exporte werden nicht weitergegeben, wenn der Host eine Allow-List-Umgebung verwendet. Deklarieren Sie sie stattdessen im MCP-Konfigurationsblock.

  • dist/server.js fehlt — führen Sie npm run build aus.

  • Falsche node-Binärdatei — muss Node ≥ 22 sein.

• OAuth-Werkzeuge fehlen in der Werkzeugliste — LARK_ENABLED_TOOLSETS muss other enthalten.

• invalid_scope bei lark_oauth_start — einer der angeforderten Scopes ist in Ihrer App noch nicht gewährt. Öffnen Sie die Berechtigungsseite der App, aktivieren Sie die im Fehler aufgeführten Scopes, veröffentlichen Sie eine neue Version.

• invalid_client bei OAuth — LARK_DOMAIN ist für Ihre App-Region falsch (inländisch = Feishu, überseeisch = Lark).

• stdout-Verschmutzung (MCP-Client trennt sofort die Verbindung) — eine Drittanbieter-Bibliothek hat in stdout geschrieben. Überprüfen Sie die stderr-Logs. server.ts kapert bereits console.* und pino schreibt in stderr.

• Clientseitig ratenbegrenzt — passen Sie LARK_THROTTLE_BITABLE_RPS usw. über env an.

Projektlayout

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

Credits

• @larksuite/openclaw-lark von OpenClaw — MIT-Lizenz. Dieses Projekt umschließt es und hängt davon ab.

• Model Context Protocol SDK von Anthropic.

• Feishu / Lark Open Platform APIs.

Haftungsausschluss

Dies ist ein persönliches Hobbyprojekt, das "wie besehen" ohne jegliche Garantie bereitgestellt wird. Es ist kein offizielles Produkt von Feishu, Lark, ByteDance oder OpenClaw.

Dies ist ein persönliches Hobbyprojekt, das "wie besehen" bereitgestellt wird und keine Garantie beinhaltet. Dieses Projekt steht in keiner Verbindung zu den offiziellen Teams von Feishu/Lark, ByteDance oder OpenClaw. Bei Problemen melden Sie diese bitte über GitHub Issues.

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

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