Feishu-MCP-Server

Ermöglicht Cursor, Windsurf, Cline und anderen KI-gestützten Coding-Tools den Zugriff auf Feishu-Dokumente, deren Bearbeitung und strukturierte Verarbeitung. Es unterstützt zusätzlich die Aufgabenverwaltung und Benutzerinfanrisatches von Feishu – auf Basis eines Model Context Protocol-Servers.

Seit Kurzem wird das eigenständige CLI-Tool feishu-tool unterstützt, mit dem alle Feishu-Tools direkt im Terminal oder in Skripten aufgerufen werden können, ohne einen MCP-Server zu starten. In Kombination mit Feishu-Skill können AI-Agenten wie Claude Code automatisch den am besten geeigneten Weg wählen, um mit Feishu zu arbeiten.

Dieses Projekt ermöglicht es KI-Coding-Tools:

• Dokumentverarbeitung: Feishu-Dokumente direkt abrufen, verstehen, erstellen und bearbeiten – für deutlich intelligentes und effizienteres Arbeiten mit Dokumenten.

• Aufgabenverwaltung: Feishu-Aufgaben auflisten, erstellen, aktualisieren und löschen; inklusive Unteraufgaben und Mitgliederverwaltung (erfordert user-Authentifizierung).

• Benutzerinformationen: Benutzer nach Namen durchsuchen oder anhand von IDs abrufen; erleichtert Aufgabenverteilung und Dokumentenzusammen – (erfordert user-Authentifizierung).

Der Ablauf entspricht dem realen Arbeitsfluss mit Feishu-Dokumenten und hilft dabei, die Dokumentressourcen effizient zu nutzen:

1. Ordnerübersicht abrufen: Schnell alle Dokumente in einem Feishu-Ordner anzeigen und durchstöbern, für Gesamtverwaltung und Suche.

2. Inhalte abrufen und verstehen: Strukturierte, blockweise, Rich-Text- und weitere multidimensionale Lese-Typen unterstützt; die KI versteht den Dokumentkontext präzise.

3. Intelligentes Erstellen und Bearbeiten: Automatisches Anlegen neuer Dokumente, Batch-Erzeugung und -Bearbeitung von Inhalten für vielseitige Anforderungen.

4. Effiziente Suche und Navigation: Eine eingebaute Schlagwortsuche findet in umfangreichen Beständen schnell die gesuchten Informationen.

5. Aufgabenverwaltung und Benutzerabfrage: CRUD für Feishu-Tasks sowie Suche nach Benutzerinformationen, um Tasks und Mitarbeiter im Dokument zu verknüpfen.

Das Projekt ermöglicht Ihnen eine intelligente Abrufen, Bearbeiten und Suchen im täglichen Arbeitsablauf mit Feishu-Dokumenten sowie eine Erweiterung um Aufgaben- und Benutzerverwaltung – für mehr Effizienz und ein besseres Erlebnis bei der Inhaltsverarbeitung.

💡 Projektempfehlung

Für die gemeinsame Nutzung mit Claude Code wird claude-ip-guard empfohlen – es erkennt die IP-Geolocation automatisch und blockt Zugriff aus beschränkten Regionen, um zu verhindern, dass das Claude-Konto durch Netzwechsel gesperrt wird.

🎬 Vorführungsvideo

Die realen Einsatzmöglichkeiten und den Ablauf des MCP findest du du in den folgenden Videos:

⭐ Star dieses Projekt, um neue Funktionen und wichtige Updates sofort zu erhalten! Wenn du dem Projekt folgst, verpasst du keine neuen Features, Fixes und Optimierungen und kannst es weiterhin effizient nutzen. Deine Unterstützung hilft auch, das Projekt zu verbessern und auszubauen. ⭐

🛠️ Details zu den Werkzeug-Funktionen

🎨 Unterstützte Formatierungsstile (deckt im Wesentlichen alle Markdown-Formate ab)

• Textstil: Fett, kursiv, unterstrichen, durchgestrichen, Inline-Code

• Textfarben: Grau, Braun, Orange, Gelb, Grün, Blau, Violett

• Ausrichtung: Linksbündig, zentriert, rechtsbündig

• Überschriften: Unterstützt Überschriften von Level 1 bis 9

• Codeblock: Syntaxhervorhebung für viele Programmiersprachen

• Listen: sortierte Liste (nummeriert), unsortierte Liste (Aufzählungszeichen)

• Bilder: Unterstützt lokale Bilder und Bilder aus dem Netz

• Formel: Mathematische Formeln innerhalb von Textblöcken; LaTeX-Syntax wird unterstützt

• Mermaid-Diagramm: Unterstützt Flussdiagramme, Sequenzdiagramme, Mindmaps, Klassendiagrammdiagramm, Kuchendiagramme, usw.

• Tabelle: Erstellt Tabellen mit mehreren Zeilen und Spalten; Zellen können Text, Überschriften, Listen, Codeblöcke usw. enthalten

• Feishu-Whiteboard –: Unterstützt Whiteboard-Erstellung in Feishu-Dokumenten für reichhaltigere und vielfältigere Inhalte.

📈 Eine Woche voraus: Effizientere Werkzeuge

• Verschlanktes Toolset: 21 Tools → 13 Tools, Redundanz reduziert, Kernfunktionen im Fokus 0.0.15 ✅

• Optimierte Beschreibungen: 7000+ tokens → 3000+ tokens, einfachere Prompts, Tokens gespart 0.0.15 ✅

• Batch-Erweiterungen: Batch-Updates und Bild-Batch-Upload, Effizienz pro Vorgang um 50 % erhöht 0.0.15 ✅

• Ablaufverbesserung: mehrfältige Aufrufe reduzieren, für komplexe Aufgaben nur einen Schritt

• Unterstützung mehrerer Schutz : tenant_access_token und user_access_token, für verschiedene Synergien (Feishu-App-Konfigurationsänderung) 0.0.16 ✅

• Unterstützt Cursor-Benutzerlogin: Login in Cursor-Plattform – nicht mehr, unnötig ❌

• Mermaid-Diagramme：Fluss-, Sequenzdiagramme usw., um Dokumente zu bereichern 0.1.11 ✅

• Tabellenunterstützung: Komplexe Tabellen mit verschiedenen Blockarten erstellen, inklusive Styling-Kontrolle 0.1.2 ✅

• Feishu-Vielfacheuser-Unterstützung: Eine Person deployt, mehrere Personen verwenden 0.1.3 ✅

• Automatische user_access_token-Aktualisierung: keine häufige neue Autorisierung, besseres Nutzerlebnis 0.1.6 ✅

• Berechtigungs-Überprüfung: prüft die Zuweisungen der Anwendung auf Erfüllung der Tool-Anforderungen; falls nicht erfüllt, wird eine verständliche Anleitung für eine reibungsfreie Nutzung gegeben 0.1.7 ✅

• Whiteboard-Inhalte erstellen: gegen Mermaid bieten Whiteboards reichhaltiger und vielfältige Inhalte mit freundlicherer und angenehmerer visuellen Gestaltung 0.1.7 ✅

• FeishuAppId und AppSecret aus Umgebungsvariablen extrahieren: FeishuKonfiguration von z. B. feishuAppId und AppSecret trennen, in Clients wie Cursor einstellen, sodass ein Dienst für mehrere Teams nutzbar ist

• Wissensbasis und "MeineWissens unterstützen**: Knoten-Travers, Knoten-Erstellung, Dateierstellung, Suche in Wissensbasis und eigener Dokumentenbibliothek` (Feishu-App-Konfigurationsänderung) 0.1.8 ✅

• Versions-Benachrichtigungen: Hinweiss bei neuen Versionen, um noch relevanten Updates zu informieren.

• Bugfix: `user-Authentifizierung im stdio-Modus: Behebt einen fehlgeschlagenen Feishu-User-Login im stdio-Modus 0.1.9 ✅

• Bereitstellung der Berechtigungsprufung konfigurieren: über FEISHU_SCOPE_VALIDATION oder --feishu-scope-validation steuerbar; standardmäßig aktiv 0.2.0 ✅

• **Cache-Verzeichnis ****: Tokens und andere Caches im systemweiten Konfigurationsordner speichern 0.2.2 ✅ Dank an Molunerfinn, leeeezx, Master-cai für Vorschläge und Code

• mcpTool Code überarbeitet: Struktur neu angelegt, für zukünftige Erweiterungen 0.2.3 ✅

• Task-Management: Ordnen, erstellen, aktualisieren und löschen von Feishu-Task; Untertasks und Mitgliederverwaltung 0.2.4 ✅

• Benutzerabfrage: Suche nach Name oder ID; erleichtert Aufgabenzuweisung und Dokumenten-Gruppenarbeit 0.2.4 ✅

• Tool-API-Ebene extrahiert – eine neue API-Ebene gleichbenannt auf die Tool-Schicht, lambda einheitliche Parameterprüfung, Bootberechnung und Fehlerfilter ✅

• CLI-Kompatibilität: Aufrufe wie feishu-tool <tool-name> '<json>' für Skripte und Automatisierung 0.2.6 ✅

• Weiterentwickeltes Skill: Feishu-Skill wird bereitgestellt, um AI-AGents like Claude Code zu unterstützen, den feishu-mcp-CLI im passenden Kontext zu nutzen 0.2.6 ✅

🔧 Feishu-Konfiguration – Leitfaden

⚠️ Wichtiger Hinweis : Vor der Verwendung ist die Feishu-App-Konfiguration zwingend erforderlich. Ohne erfolgreiche App-Konfiguration ist das Tool nicht nutzbar.

Die Erläuterung, wie man eine Feishu-App erstellt und App-Anmeldedaten erhält, finden Sie in offiziellen Tutorial.

Ausführliche Einrichtungs-Schritte für die Feishu-App: Im FEISHU_CONFIG.md – Bottom werden das Anlegen der Feishu-Anwendung, das Setzen der Berechtigungen und das Hinzufügen von Dokumenten-Zugriff Schritt für Schritt beschrieben.

🚀 Schnellstart

Variant 1: Schnellstart mit NPM

npx feishu-mcp@latest --feishu-app-id=<你的飞书应用ID> --feishu-app-secret=<你的飞书应用密钥> --feishu-auth-type=<tenant/user> --enabled-modules=<document,task>

Variant 2: Lokaler Start

1. Projekt klonen

   git clone https://github.com/cso1z/Feishu-MCP.git
   cd Feishu-MCP

2. Umgebungsvariablen setzen (Kopieren Sie .env.example als .env)

3. .env-Datei bearbeiten Öffnen Sie die .env-Datei im Projekt-Stammverzeichnis mit einem Texteditor und tragen Sie die Feishu-Anwendungs-Kennungen ein:

   FEISHU_APP_ID=cli_xxxxx
   FEISHU_APP_SECRET=xxxxx
   PORT=3333
   FEISHU_AUTH_TYPE=tenant/user
   FEISHU_ENABLED_MODULES=document,task

4. Server starten

   Variante 1: Lokal

   • Abhängigkeiten installieren

     pnpm install

   • Dienst starten

     pnpm run dev

   Variante 2: Docker Compose

   • Dienst starten

     docker-compose up -d

   • Logs anzeigen

     docker-compose logs -f

🖥️ feishu-tool CLI-Werkzeug

Seit Version 0.2.5 ist die NPM-Package feishu-mcp um das eigenständige CLI-Tool feishu-tool erweitert. Damit können Sie alle Feishu-Funktionen aus Terminal, Shell-Skripten oder AI-Agenten direkt aufrufen, ohne MCP-Server starten zu müssen.

Installation

# 全局安装（推荐）
npm install -g feishu-mcp@latest

Konfiguration

# 1. 查看 CLI 概览（子命令 + 可用工具集）
feishu-tool --help

# 2. 查看初始化指南（获取 App ID / Secret 的步骤说明）
feishu-tool guide

# 3. 写入凭证
feishu-tool config set FEISHU_APP_ID cli_xxxxx
feishu-tool config set FEISHU_USER_KEY "$(node -e 'console.log(crypto.randomUUID())')"
# FEISHU_USER_KEY 建议每个本地用户或客户端保持唯一

# 4. 查看当前配置（确认写入正确）
feishu-tool config

# 5. 查看某个工具的详细参数
feishu-tool help create_feishu_document

# 6. 调用工具
feishu-tool create_feishu_document '{"title": "测试文档"}'

Die vollständigen Parameter-Beschreibung finden Sie in der Dokumentation unter Feishu-Skill.

⚙️ Projektkonfiguration

Umgebungsvariablen

Verwendete Module

Konfigurationsdateien (für Cursor, Cline usw.)

stdio-Modus (empfohlen)

{
  "mcpServers": {
    "feishu-mcp": {
      "command": "npx",
      "args": ["-y", "feishu-mcp@latest", "--stdio"],
      "env": {
        "FEISHU_APP_ID": "<你的飞书应用ID>",
        "FEISHU_APP_SECRET": "<你的飞书应用密钥>",
        "FEISHU_AUTH_TYPE": "<tenant/user>",
        "FEISHU_ENABLED_MODULES": "document,task",
        "FEISHU_USER_KEY": "<你的用户标识>"
      }
    }
  }
}

SSE-Modus

{
  "mcpServers": {
    "feishu_local": {
      "url": "http://localhost:3333/sse?userKey=123456"
    }
  }
}

HTTP-Streamable-Modus

{
  "mcpServers": {
    "feishu_streamable": {
      "url": "http://localhost:3333/mcp?userKey=123456"
    }
  }
}

Bearer-Token-Authentifizierung (optional)

Sofern die Umgebungsvariable MCP_BEARER_TOKEN gesetzt ist, verlangen alle HTTP/SSE/StreamableHTTP-Endpunkte den Header Authorization: Bearer <token>. Dies ist für öffentliche Bereitstellung, gegen unbefugten Zugriff.

Konfigurationsbeispiel:

# .env 文件
MCP_BEARER_TOKEN=your-secret-token-here

Client-Konfigurationsbeispiel (SSE-Modus + Bearer) :

⚠️ Die meisten MCP-Clients (z. B. Cursor, Cline) unterstützen aktuell keine benutzerdefinierten Header bei SSE/StreamableHTTP-Verbindungen. Wenn Sie BearerAuth verwenden möchten, prüfen Sie, ob Ihr Client den Authorization-Header überträgt, oder lösungen Sie eine Reverse-Proxy vor der Auth (z. B. Nginx).

Für APIs oder Clients mit benutzerdefiniertem Header:

# SSE 连接示例
curl -H "Authorization: Bearer your-secret-token-here" http://localhost:3333/sse?userKey=123456

# StreamableHTTP 请求示例
curl -X POST -H "Authorization: Bearer your-secret-token-here" -H "Content-Type: application/json" http://localhost:3333/mcp?userKey=123456

⚠️ Wichtig: Der userKey in der URL ist eine Kennung des Benutzers und sehr wichtig. Füllen Sie ihn bitte aus und machen Sie ihn möglichst zufällig.

Zur Weitergabe der userKey gibt es zwei Möglichkeiten:

• URL-Query-Parameter: ?userKey=123456 (empfohlen, varig zu konfigurieren)

• Header: user-key: 123456 (geignet für Szenarien mit verweblicher Overhead)

📝 Nutzungstipp (Wichtig)

1. Empfohlene Angabe eines Zielordners:

   Beim Erstellen eines neuen Dokuments wird empfohlen, den Feishu-Ordner-Token aktiv anzugeben (entweder für einen konkreten Ordner oder den Stammordner), damit das Dokument effizienter gefunden und verwaltet werden kann. Wenn du dir über die genaue Unterordnerstruktur nicht sicher bist, kannst du das LLM automatisch unter dem angegebenen Ordner nach dem am besten geeigneten Unterordner suchen und dort das Dokument erstellen lassen.

   Wie erhalte ich den Ordner-Token? Öffne die Feishu-Ordnerseite, kopiere den Link (z. B. https://.../drive/folder/xxxxxxxxxxxxxxxxxxxxxx), und der Token ist die Zeichenfolge am ende des Links (z. B. xxxxxxxxxxxxxxxxxxxxxx. Teile den echten Token mit niemandem).

   图片上传路径说明: Die Bildpfade unterstützen beim lokalen Ausführen von MCP sowohl lokale absolute Pfade als auch http/https-Webbilder. In der Serverumgebung nur unterstützt sind. (Aufgrund der Paramterlängenbeschränkung von Cursor beim Aufrufen von MCP werden derzeit keine direkten Bilddatei-Uploads unterstützt; bitte verwende Bildpfade oder Links zum Hochladen.)

2. Formelverwendung:

   In Textblöcken können normaler Text und Formelelemente gemischt werden. Formeln verwenden die LaTeX-Syntax, z. B. 1+2=3, \frac{a}{b} oder \sqrt{x}. Es wird unterstützt, in einem einzelnen Textblock mehrere nebeneinander mehrere Formeln und normalen Text einzufügen.

3. Verwende die Feishu-Benutzerauthentifizierung:

   • Die Benutzerauthentifizierung (user) unterscheidet sich von der Mandantenauthentifizierung (tenant) bei der Erweiterung von Berechtigungen. Daher muss beim ersten Wechsel von Tenant zu Benutzer (demo) die konfigurierten Berechtigung beachtet werden.

   • Um Benutzer zu unterscheiden, muss die Benutzerkennung auf die eine oder andere der beiden Wege angezeigt werden.

   • URL-Abfrageparameter: Füge ?userKey=123456 zur MCP-Server-URL hinzu.

   • Request-Header: Übergib den Header user-key: 123456.

   Der Wert ist die eindeutige Kennung des Benutzers. Deshalb ist er bei der Einrichtung umso besser, je zufälliger er gewählt wird.

4. Dringend empfehlene Benutzerauthentifizierung:

   Die Mandantenauthentifizierung unterliegt vielen Label-Einschränkungen, unter anderem im Hinblick auf Dateizugriffsberechtigungen, die Kompatibilität mit der Feishu OpenAPI (Wiki-Dokumente können nicht durchsucht werden), sowie beim Erstellen und Bearbeiten von Dokumenten und bei der Rechtshabe – das ist Ihren Nachteil gegenüber der Benutzerauthentifizierung.

5. Funktionen für Aufgaben und Benutzerinformationsabfragen:

   Möchtest du die Feishu-Aufgaben (To-Do-Liste, Erstellen von Aufgaben, Zuweisen von Verantwortlichen) von KI verwalten oder Informationen über Kollegen suchen? Dafür sind zwei Schritte nötig: ① Fordere den user-Authentifizierungsmodus an (im tenant-Modus stehen diese Module nicht zur Verfügung); ② Setze in der Konfiguration FEISHU_ENABLED_MODULES=document,task. Nach Aktivierung von task ist die Benutzersuche automatisch verfügbar – ohne weitere Konfiguration.

6. Lark International verwenden:

   Die Feishu-Version für China benötigt keine zusätzliche Konfiguration. Falls dein Team Lark International oder ein selbstgehostetes Feishu verwendet, ist die Einstellung zusätzlich vorgenommen werden: [GXP15]

7. Trennung von Intranet-Zugriff und Extranet-Aufruf-Zurückweg:

   Wenn der MCP-Client die Intranet-Adresse des Dienstes (z. B. http://feishu-mcp:3333/mcp) verwendet, aber der OAuth-Callback von Feishu auf eine öffentliche Domain zugreifen muss, kannst du zusätzliches Konfigurationsfeld setzen: Weitere Einstellung: [GXP16]

   Dadurch kann der Client weiterhin die Intranet-Adresse verbinden, der für die Benutzer zurückgegebene Autorisierungslink verwendet aber https://somo-feishu-mcp.yfgao.net/callback als Callback-Adresse.

8. Dynamischer Wechsel des userKey in einer Mehrmandanten-Netzarchitektur: In einer Mehrmandanten-Relay-Architektur fictional im System den Feishu-MCP-Dienst über ein integriertes Verwaltungstool. Da die zugrunde liegenden MCP-Serviceinstanzen auf Sitzungsebene wiederverwendet werden, werden die angeforderten unterschiedlicher Benutzer tatsächlich in gemeinsam genutzten Sitzungskontext ausgeführt. Daher muss das System die dynamische Wechsel über den user-key-Headerwert ermöglichen, um eine Isolierung von Mandantenidentitäten und Kontextpropagation zu realiseren und die Bedarfsszenario gleichzeitiger Zugriffe vieler Benutzer abzudecken.

   So wird userKey gewechselt:

   • Im HTTP-Streamable-Modus können spätere Anfragen die Benutzerkennung der aktuellen Sitzung ändern, indem im Header user-key mitgesandt wird.

   • Übertragungsmethode: In der Anfrageheader user-key: <neue Benutzerkennung> hinzufügen.

   • Beispielszenario: Nachdem Benutzer A seine Operation abgeschlossen hat, überträgt die Anfrage von Benutzer B eine user-key: userB-Header – das System wird die Sitzung automatisch auf den Kontext von Benutzer B wechseln.

   Achtung: Diese Funktion ist nur im HTTP-Streamable-Modus verfügbar; SSE- und stdio-Modi unterstützen kein dynamisches Umschalten.

🚨 Fehlerbehandlung bei der Diagnose

Berechtigungsprobleme-Erklärcomputer

Nur für Beratungszwecke: die Konfigurationshinweise unter? Anleitung in FEISHU_CONFIG.md.

Problemidentifizierung

1. Anwendungsberechtigungen prüfen: Stelle sicherstellen, dass die Anwendung die erforderlichen Dokumentzugriffsberechtigungen erhalten hat.

2. Dokument-Autorisierung prüfen: Stelle sicher, dass das Zieldokument an die Anwendung oder die zur Anwendung gehörden Gruppe authorisiert wurde.

3. Zulässigen Bereich prüfen: Gibt es sicher, dass der in der Veröffentlichung der Anwendung angegebene Verfügbarkeitsbereich die Dokumentbesitzer enthält.

Berechtigungsprüfung und -behebung

1. Token abrufen: app_Den Zugriffstoken für eigene App holen

2. Mit dem Token aus Schritt 1 prüfen erneut, ob Zugriff auf dieses Dokument besteht: Dokumentgrundinformationen abrufen

Häufige Probleme

• App kann nicht gefunden werden: Prüfen, ob die App-Anwendung veröffentlicht wurde und der Verfügbufbereich korrekt konfiguriert ist.

• Nicht genügend Rechte: Siehe Häufige Fragen zu Cloud-Dokumenten (Feishu)

• Wissensbasiszugriff problem: Siehe Häufige Fragen zur Wissensbasis (Feishu)

📚 Entwickler-Wiki

Detaillierte Dokumentation und technische Leitfäden, die umfassende Hilfen für Lernende und MitwirkendeGeben:

• Wiki-Startseite – Vollständiges Dokumentinhaltsverzeichnis und Schnellnavigation

• Architekturübersicht – Beschreibung und Technologie-Stack der Gesamtarchitektur

• Einblick in die Kernmodule – Implementierungsdetails und Code-Beispiele der einzelnen Module

• Authentifizierung und Autorisierung – Token-Verwaltung und Mechanismen zur Unterstützung mehrerer Benutzer

• Leitfaden für Entwickler – Umgebungseinrichtung, Entwicklungsablauf und Debugging-Techniken

• API-Referenz – Vollständige Dokumentation über alle Tools und Funktionen

• Beste Vorgehensweisen – Codierungsstandards, Leistungsabstimmung und Sicherheit

• Implementation des MCP-Protokolls – Ausführliche Erläuterung des MCP-Protokolls und Transportschicht

💖 Projekt-Unterstützungs

Wenn dieses Projekt dir geholfen hat, ziehen eine dieser Möglichkeiten unterstützen:

• ⭐ Gib dem Projekt einen Stern (Star)

• 🐛 Bug und Fehler melden

• 💡 Featurewünsche -Neue Ideen vorschlagen

• 📖 Die Dokumentation verbessern

• 🔀 Einen Pull Request-Erstellen

Deine Unterstützung ist der Antrieb für unseren Fortschritt!

Star History

1. ### Empfohlene Angabe eines Zielordners:

Beim Anlegen eines neuen Dokuments wird empfohlen, den Feishu-Ordner-Token aktiv anzugeben (entweder für einen konkreten Ordner oder den Stammordner), damit das Dokument effizienter gefunden und verwaltet werden kann. Wenn du dir über den genauen Unterordner nicht sicher bist, kannst du das LLM automatisch in dem angegebenen Ordner nach dem am besten geeigneten Unterordner suchen und dort das neue Dokument anlegen lassen.

Wie erhalte ich den Ordner-Token? Öffne die Feishu-Ordnerseite, kopiere den Link (z. B. https://.../drive/folder/xxxxxxxxxxxxxxxxxxxxxx). Der Token ist die Zeichenfolge am Ende des Links (z. B. xxxxxxxxxxxxxxxxxxxxxx). Gib den echten Token niemals weiter.

2. Hinweise zum Bild-Upload-Pfad:

   Bei lokalem Betrieb von MCP unterstützen Bildpfade sowohl lokale absolute Pfade als auch http/https-Netzwerkbilder; in einer Server-Umgebung werden ausschließlich Netzwerkbild-Links unterstützt (aufgrund der Parameterlängenbeschränkung von Cursor beim Aufruf von MCP kann der direkte Upload der Bilddatei selbst derzeit nicht unterstützt werden; bitte verwende Bildpfade oder Links zum Hochladen).

3. Hinweise zur Formelverwendung:

   In Textblöcken können normaler Text und Formelelemente gemischt werden. Formeln verwenden die LaTeX-Syntax, z. B. 1+2=3, \frac{a}{b}, \sqrt{x} usw. Es wird unterstützt, mehrere Formeln und normalen Text in demselben Textblock zu kombinieren.

4. Feishu-Benutzer-Authentifizierung verwenden:

   Die Benutzer-Authentifizierung (user) unterscheidet sich von der Mandanten-Authentifizierung (tenant) bei der Erweiterung von Berechtigungen. Beim erstmaligen Wechsel von tenant zu user muss daher besonders auf die konfigurierten Berechtigungen geachtet werden. Um verschiedene Benutzer zu unterscheiden, muss die Benutzerkennung userKey übergeben werden. Zwei Methoden werden unterstützt:

   • URL-Abfrageparameter: In der MCP-Server-URL ?userKey=123456 ergänzen

   • Request-Header: Den Header user-key: 123456 übergeben

   Dieser Wert ist die eindeutige Kennung des Benutzers, daher sollte er bei der Einrichtung möglichst zufällig gewählt werden.

5. Benutzer-Authentifizierung wird dringend empfohlen:

   Die Mandanten-Authentifizierung (tenant) weist viele Einschränkungen auf – etwa bei Dateizugriffsrechten, bei der Feishu-OpenAPI-Kompatibilität (keine Suche in Wiki-Dokumenten) oder bei Erstellungs- und Bearbeitungsprotokollen von Dokumenten – und ist der Benutzer-Authentifizierung (user) in diesen Punkten unterlegen.

6. Funktionen für Aufgaben und Benutzerinformationen:

   Möchtest du KI nutzen, um Feishu-Aufgaben zu verwalten (To-do-Liste anzeigen, Aufgaben erstellen, Verantwortliche zuweisen) oder Kollegen zu finden? Dafür sind zwei Schritte nötig: ① user-Authentifizierung verwenden (im tenant-Modus werden diese Fähigkeiten nicht bereitgestellt); ② in der Konfiguration FEISHU_ENABLED_MODULES=document,task setzen. Nach Aktivierung von task ist die Benutzersuche automatisch verfügbar, ohne zusätzliche Konfiguration.

7. Lark International verwenden:

   Die chinesische Feishu-Version benötigt keine zusätzliche Konfiguration. Falls dein Team Lark International oder ein selbst gehostetes Feishu verwendet, muss zusätzlich eingerichtet werden:

   FEISHU_BASE_URL=https://open.larksuite.com/open-apis
   FEISHU_AUTH_BASE_URL=https://accounts.larksuite.com

8. Trennung von Intranet-Zugriff und externem Callback:

   Wenn der MCP-Client den Dienst über eine interne Adresse erreicht (z. B. http://feishu-mcp:3333/mcp), der OAuth-Callback von Feishu jedoch über eine öffentliche Domain laufen muss, kann zusätzlich konfiguriert werden:

   FEISHU_PUBLIC_BASE_URL=https://somo-feishu-mcp.yfgao.net

   Der Client kann die intene Adresseweiter verwenden, während der den Benutzern zurückgegebene Autorisierungslink https://somo-feishu-mcp.yfgao.net/callback als Callback-Adresse verwendet.

9. Dynamischer Wechsel von userKey in Mehr-Mandanten-Relay-Architektur:

   In einer Mehrmieter-Relay-Architektur wird der Feishu-MCP-Dienst über ein integriertes Verwaltungstool zentral erhöht. Da die zugrunde liegenden MCP-Dienstinstanzen auf Session-Ebene wiederverwendet werden, laufen die Anfragen verschiedener Benutzer tatsächlich im gemeinsam genutzten Session-Kontext. Daher muss das System über den durchgereichten user-key-Request-Header einen dynamischen Wechsel unterstützen, um die Isolierung der Mandantenidentität und die Kontextinjektion zu ermöglichen und so die Anforderungen des gleichzeitigen Zugriffs mehrerer Benutzer zu erfüllen.

   Wie der userKey gewechselt wird:

   Im HTTP-Streamable-Modus kann der aktuelle BenutzeridentFizier der Sitzung über den user-key-Request-Header aktualisiert werden.

   • Übertragungsart: user-key: <neue Benutzerkennung> im Request-Header angeben

   • Beispielszenario: Nachdem Benutzer A seine Aktion abgeschlossen hat, wird bei der Anfrage von Benutzer B user-key: userB übergeben; das System wechselt automatisch auf den Kontext sshcweiter von Benutzer B.

   Hinweis: Diese Funktion ist nur im HTTP-Streaming-Modus verfügbar; der Weiß-Modus unterstützt die SSE- und stdio-Modi nicht.

🚨 Fehlerdiagnose

Prüfung von Berechtigungsproblemen

Prüfe hier zuerst die Konfigurationspunkte: Schritt-für-Schritt-Anleitung FEISHU_CONFIG.md.

Problemerfassung

1. Anwendungsberechtigungen prüfen: Stelle sicher, dass die Anwendung über die erforderlichen Dokumentzugriffsrechte verfügt.

2. Dokumentautorisation prüfen: Vergewissere dich, dass das Zieldokument für die Anwendung bzw. ihrere Gruppe autorisiert ist.

3. Verfügbarkeitsbereich prüfen: Stelle sicher, dass der Verfügungsbereich der veröffentlichten Version die Dokumentbesitzer enthält.

Berechtigungsprüfung und -behebung

1. Token abrufen: app_access_token für selbst erstellte App abrufen

2. Mit dem Token aus Schritt 1 prüfen, ob Zugriff auf das Dokument besteht: Dokumentbasisinformationen abrufen

Häufige Probleme

• Anwendung nicht gefunden: Prüfe, ob die Anwendung veröffentlicht wurde und der Verfügbarkeitsbereich korrekt konfiguriert ist.

• Unzureichende Berechtigungen: Siehe Häufige Fragen zu Cloud-Dokumenten

• Probleme beim Aufrufen der Wissensbasis: Siehe Häufige Fragen zur Wissensbasis

📚 Entwickler-Wiki

Detaillierte Entwicklungsdokumentation und technische Anleitungen mit umfassender Unterstützung für Lernende und Mitwirkende:

• Wiki Startseite – Vollständiges Dokument-Inhaltsverzeichnis und Schnellnavigation

• Architekturdesign – Gesamtbeschreibung der Architektur und des Technologie-Stacks

• Detail der Kernmodule – Implementierungsdetails und Codebeispiele für jedes Modul

• Authentifizierung und Autorisierung – Token-Verwaltung und Mechanismen für mehrere Nutzer

• Entwicklerleitfaden – Einrichtung der Umgebung, Entwicklungsworkflow und Debugging-Tipps

• API-Referenz – Detaillierte Dokumentation aller Werkzeugfunktionen

• Best Practices – Codestandards, Leistungsoptimierung und Sicherheits-praktiken

• MCP-Protokollimplementierung – Detaillierung des MCP-Protokolls und Implementierung der Transportschicht

💖 Projekt unterstützen

Wenn dir dieses Projekt geholfen hat, ziehe bitte in Betracht:

• ⭐ Dem Projekt einen Stern zu geben

• 🐛 Fehler und Probleme zu meldieren

• 💡 Neue Funktionsvorschlägen einzureichen

• 📖 Die Dokumentation zu verbessern

• 🔀 Einen Pull Request einzureichen

Deine Unterstützung ist unsere Antriebskraft für Fortschritt!

Star-Historie